Zarządzanie kontami użytkowników

Interfejs Directory API udostępnia metody programowe do tworzenia, aktualizowania i usuwania użytkowników. Możesz też uzyskać informacje o pojedynczych użytkownikach lub listach użytkowników, którzy spełniają określone kryteria. Oto przykłady niektórych podstawowych działań użytkownika.

Tworzenie konta użytkownika

Możesz dodać konto użytkownika do dowolnej domeny na koncie Google Workspace. Zanim dodasz konto użytkownika, potwierdź własność domeny.

Jeśli uaktualniliśmy Twoje osobiste konto Gmail do firmowego konta e-mail z własną nazwą domeny, nie możesz utworzyć nowych kont użytkowników, dopóki nie odblokujesz dodatkowych ustawień Google Workspace. Szczegółowe informacje znajdziesz w artykule Firmowe konta e-mail w G Suite zostały przekształcone w konta G Suite Basic.

Aby utworzyć konto użytkownika w jednej z Twoich domen, użyj tego żądania POST i dołącz autoryzację opisaną w artykule Więcej informacji o uwierzytelnianiu i autoryzacji. Dostępne zakresy interfejsu Directory API możesz wyświetlić na liście zakresów OAuth 2.0. Właściwości ciągu zapytania żądania znajdziesz w metodie users.insert(). 

POST https://admin.googleapis.com/admin/directory/v1/users

W przypadku wszystkich próśb o utworzenie musisz przesłać informacje potrzebne do zrealizowania prośby. Jeśli używasz bibliotek klienta, konwertują one obiekty danych z wybranego języka na obiekty w formacie danych JSON.

Żądanie JSON

Poniższy dokument JSON zawiera przykładowe żądanie tworzenia użytkownika. Pełną listę właściwości żądań i odpowiedzi znajdziesz w dokumentacji interfejsu API. 

{
"primaryEmail": "[email protected]",
"name": {
 "givenName": "Elizabeth",
 "familyName": "Smith"
},
"suspended": false,
"password": "new user password",
"hashFunction": "SHA-1",
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
 {
  "type": "work",
  "protocol": "gtalk",
  "im": "[email protected]",
  "primary": true
 }
],
"emails": [
 {
  "address": "[email protected]",
  "type": "home",
  "customType": "",
  "primary": true
 }
],
"addresses": [
 {
  "type": "work",
  "customType": "",
  "streetAddress": "1600 Amphitheatre Parkway",
  "locality": "Mountain View",
  "region": "CA",
  "postalCode": "94043"
 }
],
"externalIds": [
 {
  "value": "12345",
  "type": "custom",
  "customType": "employee"
 }
],
"organizations": [
 {
  "name": "Google Inc.",
  "title": "SWE",
  "primary": true,
  "type": "work",
  "description": "Software engineer"
 }
],
"phones": [
 {
  "value": "+1 nnn nnn nnnn",
  "type": "work"
 }
],
"orgUnitPath": "/corp/engineering",
"includeInGlobalAddressList": true
}

Jeśli częstotliwość żądań dotyczących tworzenia jest zbyt wysoka, serwer interfejsu API może zwracać odpowiedzi HTTP 503, które wskazują, że został przekroczony limit. Jeśli otrzymasz takie odpowiedzi, użyj algorytmu wygaszania się, aby ponownie wysłać żądania.

Warto wiedzieć o nowym koncie:

  • Jeśli na koncie Google zakupiono licencje na pocztę, nowemu użytkownikowi zostanie automatycznie przypisana skrzynka pocztowa. Ukończenie i aktywowanie tego zadania może potrwać kilka minut.
  • Edytowanie pola tylko do odczytu w żądaniu, np. isAdmin, jest ignorowane przez usługę interfejsu API.
  • Maksymalna dozwolona liczba domen na koncie to 600 (1 domena podstawowa i 599 dodatkowych domen).
  • Jeśli podczas tworzenia konta użytkownika nie został on przypisany do konkretnej jednostki organizacyjnej, konto znajduje się w jednostce organizacyjnej najwyższego poziomu. Jednostka organizacyjna użytkownika określa, do których usług Google Workspace ma on dostęp. Jeśli użytkownik zostanie przeniesiony do nowej organizacji, jego dostęp się zmieni. Więcej informacji o strukturach organizacyjnych znajdziesz w Centrum pomocy administracji. Więcej informacji o przenoszeniu użytkownika do innej organizacji znajdziesz w artykule Aktualizowanie użytkownika.
  • W przypadku nowych kont użytkowników wymagane jest password. Jeśli podano wartość hashFunction, hasło musi być prawidłowym kluczem haszowania. Jeśli nie jest określone, hasło powinno być w postaci zwykłego tekstu i mieć od 8 do 100 znaków ASCII. Więcej informacji znajdziesz w dokumentacji interfejsu API.
  • W przypadku użytkowników korzystających z abonamentu elastycznego Google Workspace tworzenie użytkowników za pomocą tego interfejsu API będzie miało wpływ na koszty i spowoduje obciążenie konta rozliczeniowego klienta. Więcej informacji znajdziesz w informacjach o rozliczeniach w interfejsie API.
  • Konto Google Workspace może obejmować dowolną z Twoich domen. Na koncie z wieloma domenami użytkownicy z jednej domeny mogą udostępniać usługi użytkownikom z innych domen na koncie. Więcej informacji o użytkownikach w wielu domenach znajdziesz w artykule Informacje o użytkownikach w wielu domenach.
  • Być może masz konta będące w konflikcie. Sprawdź, czy osoba, którą chcesz dodać, ma już konto Google. Następnie wykonaj odpowiednie czynności, aby uniknąć konfliktów między tymi kontami. Zobacz Znajdowanie i rozwiązywanie konfliktów między kontami.
  • Mogą to być konta gości. Jeśli użytkownicy zaproszą osoby spoza organizacji, które nie mają kont Google, do współpracy w Google Dysku, otrzymają one konta gościa w formacie nazwa_użytkownika_gościa@Twoja_domena.com. Jeśli dodasz użytkownika z tą samą nazwą użytkownika co konto gościa, konto zostanie przekonwertowane na pełne konto Google Workspace. Konto zachowa aktualne uprawnienia do plików na Dysku. Zobacz Udostępnianie dokumentów użytkownikom.

Pomyślna odpowiedź zwraca kod stanu HTTP 200. Oprócz kodu stanu odpowiedź zawiera też właściwości nowego konta użytkownika.

Aktualizowanie konta użytkownika

Aby zaktualizować konto użytkownika, użyj poniższego żądania PUT i dołącz autoryzację opisaną w artykule Autoryzowanie żądań. userKey może być podstawowym adresem e-mail użytkownika, unikalnym identyfikatorem użytkownika id lub jednym z aliasów adresów e-mail użytkownika.

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey

Zarówno treść żądania, jak i odpowiedzi zawierają wystąpienie obiektu User. Interfejs Directory API obsługuje jednak semantykę poprawki, więc w żądaniu musisz przesłać tylko zaktualizowane pola.

Przykładowe żądanie

W przykładzie poniżej givenName użytkownika „Elizabeth” zostało utworzone w momencie, gdy podano tylko adres e-mail do pracy.

{
  "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith"
   },
  "emails": [
    {
      "address": "[email protected]",
      "type": "work",
      "primary": true
    }
}

Prośba poniżej aktualizuje givenName z „Elizabeth” na „Liz” oraz dodaje adres e-mail domowy. Pamiętaj, że oba adresy e-mail są podawane ostrożnie, ponieważ pole jest tablicą.

PUT https://admin.googleapis.com/admin/directory/v1/users/[email protected]

{
  "name": {
    "givenName": "Liz",
   },
  "emails": [
    {
      "address": "[email protected]",
      "type": "work",
      "primary": true
    },
    {
      "address": "[email protected]",
      "type": "home"
    }
  ]
}

W odpowiedzi na pomyślne zakończenie operacji zwracany jest kod stanu HTTP 200 oraz zasób User ze zaktualizowanymi polami.

Podczas aktualizowania nazwy konta użytkownika pamiętaj o tych kwestiach:

  • Zmiana nazwy konta użytkownika powoduje zmianę jego podstawowego adresu e-mail i domeny używanej podczas pobierania informacji o tym użytkowniku. Przed zmianą nazwy użytkownika zalecamy wylogowanie go ze wszystkich sesji przeglądarki i usług.
  • Proces zmiany nazwy konta użytkownika może potrwać do 10 minut, zanim zostanie rozpowszechniony we wszystkich usługach.
  • Gdy zmienisz nazwę użytkownika, stara nazwa użytkownika zostanie zachowana jako alias, aby zapewnić ciągłe dostarczanie poczty w przypadku ustawień przekierowania poczty. Nie będzie ona jednak dostępna jako nowa nazwa użytkownika.
  • Ogólnie zalecamy też, aby nie używać adresu e-mail użytkownika jako klucza danych trwałych, ponieważ adres e-mail może ulec zmianie.
  • Pełną listę skutków zmiany nazwy użytkownika w aplikacjach Google Workspace znajdziesz w Centrum pomocy dla administratorów.

Przypisywanie użytkownikowi ról administratora

Aby nadać użytkownikowi uprawnienia superadministratora, użyj tego żądania POST i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. Wartością userKey może być podstawowy adres e-mail użytkownika, unikalny identyfikator użytkownika id lub jeden z aliasów adresów e-mail użytkownika. Właściwości żądań i odpowiedzi znajdziesz w dokumentacji API. Więcej informacji o super administratorze znajdziesz w Centrum pomocy. 

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/makeAdmin

Żądanie JSON

W tym przykładzie użytkownik, którego adres e-mail to [email protected], stał się superadministratorem:userKey 

POST https://admin.googleapis.com/admin/directory/v1/users/[email protected]/makeAdmin

{
 "status": true
}

Pomyślna odpowiedź zwraca kod stanu HTTP 200.

Zarządzanie relacjami z użytkownikami

Interfejs Directory API używa pola relations do definiowania różnych typów relacji między użytkownikami. W kontekście biznesowym to pole jest często używane do określania relacji między menedżerem a pracownikiem lub asystentem, ale obsługuje też wiele innych typów relacji. Relacja wyświetla się na karcie „Powiązane osoby” użytkownika w dowolnej aplikacji Google Workspace, która obsługuje tę funkcję. Przykłady miejsc, w których jest widoczna karta, znajdziesz w artykule Dodawanie informacji do profilu użytkownika w katalogu.

Tworzenie relacji między użytkownikami

Relację możesz zdefiniować tylko w jednym kierunku, zaczynając od „użytkownika nadrzędnego”, którego rekord zawiera pole relations. typeopisuje związek tej osoby z użytkownikiem. Na przykład w relacji menedżer–pracownik pracownik jest użytkownikiem właścicielskim, a do jego konta dodajesz pole relations o typie manager. Dozwolone typy znajdziesz w dokumentacji referencyjnej obiektu User.

Skonfiguruj relację, tworząc lub aktualizując użytkownika będącego właścicielem za pomocą treści żądania JSON, która zawiera pole relations. W jednym żądaniu możesz utworzyć wiele relacji.

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_1",
      "type": "manager"
    },
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "dotted_line_manager"
    }
  ]
}

Aktualizowanie i usuwanie relacji

Pola relations można aktualizować tylko jako całość. Nie możesz zmienić typu relacji ani usunąć poszczególnych osób. W przykładzie powyżej, aby usunąć istniejący związek menedżera i uczynić menedżera z kropkową linią menedżera użytkownika, zaktualizuj konto użytkownika z wszystkimi wartościami pól zgodnie z aktualnymi wymaganiami.

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "manager"
    }
  ]
}

Aby usunąć wszystkie relacje użytkownika mającego prawa własności, ustaw relations na pusty:

{
  "relations": []
}

Pobieranie użytkownika

Aby pobrać użytkownika, użyj poniższego żądania GET i dołącz autoryzację opisaną w artykule Autoryzowanie żądań. Wartością userKey może być podstawowy adres e-mail użytkownika, unikalny identyfikator użytkownika id lub jeden z aliasów adresów e-mail użytkownika. Właściwości żądań i odpowiedzi znajdziesz w dokumentacji API. 

GET https://admin.googleapis.com/admin/directory/v1/users/userKey

Ten przykład zwraca właściwości konta użytkownika, którego podstawowy lub aliasowy adres e-mail to [email protected]: 

GET https://admin.googleapis.com/admin/directory/v1/users/[email protected]

Odpowiedź JSON

Pomyślna odpowiedź zwraca kod stanu HTTP 200. Oprócz kodu stanu odpowiedź zawiera też właściwości konta użytkownika. 

{
 "kind": "directory#user",
 "id": "the unique user id",
 "primaryEmail": "[email protected]",
 "name": {
  "givenName": "Liz",
  "familyName": "Smith",
  "fullName": "Liz Smith"
 },
 "isAdmin": true,
 "isDelegatedAdmin": false,
 "lastLoginTime": "2013-02-05T10:30:03.325Z",
 "creationTime": "2010-04-05T17:30:04.325Z",
 "agreedToTerms": true,
 "hashFunction": "SHA-1",
 "suspended": false,
 "changePasswordAtNextLogin": false,
 "ipWhitelisted": false,
 "ims": [
  {
   "type": "work",
   "protocol": "gtalk",
   "im": "[email protected]",
   "primary": true
  }
 ],
 "emails": [
  {
   "address": "[email protected]",
   "type": "home",
   "customType": "",
   "primary": true
  }
 ],
 "addresses": [
  {
   "type": "work",
   "customType": "",
   "streetAddress": "1600 Amphitheatre Parkway",
   "locality": "Mountain View",
   "region": "CA",
   "postalCode": "94043"
  }
 ],
 "externalIds": [
  {
   "value": "employee number",
   "type": "custom",
   "customType": "office"
  }
 ],
 "organizations": [
  {
   "name": "Google Inc.",
   "title": "SWE",
   "primary": true,
   "customType": "",
   "description": "Software engineer"
  }
 ],
 "phones": [
  {
   "value": "+1 nnn nnn nnnn",
   "type": "work"
  }
 ],
 "aliases": [
  "[email protected]",
  "[email protected]"
 ],
 "nonEditableAliases": [
  "[email protected]"
 ],
 "customerId": "C03az79cb",
 "orgUnitPath": "corp/engineering",
 "isMailboxSetup": true,
 "includeInGlobalAddressList": true
}

Pobieranie wszystkich kont użytkowników w domenie

Aby pobrać wszystkich użytkowników w tej samej domenie, użyj tego żądania GET i dodaj autoryzację opisaną w sekcji Autoryzowanie żądań. Aby ułatwić czytanie, przykład zawiera łamania wierszy: 

GET https://admin.googleapis.com/admin/directory/v1/users
?domain=primary domain name&pageToken=token for next results page
&maxResults=max number of results per page
&orderBy=email, givenName, or familyName
&sortOrder=ascending or descending
&query=email, givenName, or familyName:the query's value*

Właściwości żądań i odpowiedzi znajdziesz w dokumentacji API.

Odpowiedź JSON

W tym przykładzie zwracane są wszystkie domeny użytkowników w domenie example.com, przy czym maksymalnie 2 domeny użytkowników na stronę odpowiedzi. W tej odpowiedzi znajduje się nextPageToken z listą użytkowników, których dotyczy problem. Domyślnie system zwraca listę 100 użytkowników w porządku alfabetycznym według adresu e-mail: 

GET https://admin.googleapis.com/admin/directory/v1/users?domain=example.com&maxResults=2

Pomyślna odpowiedź zwraca kod stanu HTTP 200. Oprócz kodu stanu odpowiedź zwraca 2 konta użytkowników w domenie example.com (maxResults=2): 

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "[email protected]",
   "name": {
    "givenName": "Liz",
    "familyName": "Smith",
    "fullName": "Liz Smith"
   },
   "isAdmin": true,
   "isDelegatedAdmin": false,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "ims": [
    {
     "type": "work",
     "protocol": "gtalk",
     "im": "[email protected]",
     "primary": true
    }
   ],
   "emails": [
    {
     "address": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "addresses": [
    {
     "type": "work",
     "customType": "",
     "streetAddress": "1600 Amphitheatre Parkway",
     "locality": "Mountain View",
     "region": "CA",
     "postalCode": "94043"
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "organizations": [
    {
     "name": "Google Inc.",
     "title": "SWE",
     "primary": true,
     "customType": "",
     "description": "Software engineer"
    }
   ],
   "phones": [
    {
     "value": "+1 nnn nnn nnnn",
     "type": "work"
    }
   ],
   "aliases": [
    "[email protected]",
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "user unique ID",
   "primaryEmail": "[email protected]",
   "name": {
    "givenName": "admin",
    "familyName": "two",
    "fullName": "admin two"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": true,
   "suspensionReason": "ADMIN",
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "contractor license number",
     "type": "custom",
     "customType": "work"
    }
   ],
   "aliases": [
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "next page token"
}

Pobieranie wszystkich użytkowników konta

Aby pobrać wszystkich użytkowników na koncie, które może składać się z wielu domen, użyj tego żądania GET i dodaj autoryzację opisaną w sekcji Autoryzowanie żądań. Aby ułatwić czytanie, przykład zawiera łamania wierszy: 

GET https://admin.googleapis.com/admin/directory/v1/users
?customer=my_customer or customerId&pageToken=token for next results page
&maxResults=max number of results per page
&orderBy=email, givenName, or familyName
&sortOrder=ascending or descending
&query=user attributes
  • Ciąg zapytania customer to wartość my_customer lub customerId.
  • Użyj ciągu my_customer, aby reprezentować customerId na swoim koncie.
  • Jako administrator sprzedawcy użyj customerId klienta, któremu sprzedajesz usługi. W przypadku customerId użyj nazwy domeny podstawowej konta w żądaniu operacji Pobierz wszystkich użytkowników w domenie. Odpowiedź zawiera wartość customerId.
  • Opcjonalny ciąg znaków orderBy określa, czy lista jest sortowana według podstawowego adresu e-mail użytkownika, nazwiska lub imienia. Gdy używasz zapytania orderBy, możesz też użyć ciągu zapytania sortOrder, aby wyświetlić wyniki w kolejności rosnącej lub malejącej.
  • Opcjonalny ciąg zapytania query umożliwia wyszukiwanie w wielu polach profilu użytkownika, w tym w polach podstawowych i niestandardowych. Przykłady znajdziesz w artykule Wyszukiwanie użytkowników.

Właściwości żądań i odpowiedzi znajdziesz w dokumentacji API.

W tym przykładzie administrator konta prosi o zwrócenie wszystkich użytkowników konta z jednym wpisem na każdej stronie odpowiedzi. nextPageToken przechodzi na następną stronę wyników: 

GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&maxResults=1

W tym przykładzie administrator sprzedawcy prosi wszystkich użytkowników na koncie sprzedawcy o przyznanie wartości C03az79cb parametrowi customerId. 

GET https://admin.googleapis.com/admin/directory/v1/users?customer=C03az79cb&maxResults=1

Odpowiedź JSON

Pomyślna odpowiedź zwraca kod stanu HTTP 200. Oprócz kodu stanu odpowiedź zawiera też wszystkich użytkowników na tym koncie: 

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "name": {
    "givenName": "admin",
    "familyName": "two",
    "fullName": "admin two"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
     "[email protected]"
   ],
   "nonEditableAliases": [
     "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith",
    "fullName": "Elizabeth Smith"
   },
   "isAdmin": false,
   "isDelegatedAdmin": false,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": false,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "[email protected]",
     "type": "home",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "bank"
    }
   ],
   "relations": [
    {
     "value": "liz",
     "type": "friend",
     "customType": ""
    }
   ],
   "aliases": [
    "[email protected]",
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "name": {
    "givenName": "Tester",
    "familyName": "Three",
    "fullName": "Tester Three"
   },
   "isAdmin": false,
   "isDelegatedAdmin": false,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "name": {
    "givenName": "Admin",
    "familyName": "Work",
    "fullName": "Admin Work"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "NNNNN"
}

Pobieranie ostatnio usuniętych kont użytkowników

Aby pobrać wszystkich użytkowników, którzy zostali usunięci w ciągu ostatnich 20 dni z konta lub z jednej z jego domen, użyj poniższych żądań GET i dodaj autoryzację opisaną w sekcji Autoryzowanie żądań. Aby cofnąć usunięcie użytkownika, zapoznaj się z artykułem Cofanie usunięcia użytkownika.

Aby odzyskać użytkowników usuniętych w ciągu ostatnich 20 dni z domeny głównej lub subdomeny konta, użyj tej prośby GET. Parametr ciągu zapytania domain to nazwa domeny podstawowej. Właściwości żądania i odpowiedzi użytkownika znajdziesz w dokumentacji API. Aby ułatwić czytanie, w tym przykładzie użyto znaków łamania wiersza: 

GET https://admin.googleapis.com/admin/directory/v1/users
?domain=primary domain name&pageToken=token for next results page
&maxResults=max number of results per page
&showDeleted=true
 Jeśli konto ma wiele domen, możesz odzyskać użytkowników, którzy zostali usunięci w ciągu ostatnich 20 dni z całego konta, używając tej prośby GET. Aby ułatwić czytanie, przykład zawiera łamania wierszy: 
GET https://admin.googleapis.com/admin/directory/v1/users
?customer=my_customer or customerId&pageToken=token for next results page
&maxResults=max number of results per page&showDeleted=true
  • Ciąg zapytania customer to wartość my_customer lub customerId.
  • Jako administrator konta używaj ciągu my_customer, aby reprezentować customerId Twojego konta.
  • Jako administrator sprzedawcy użyj customerId klienta, któremu sprzedajesz usługi. W przypadku customerId użyj nazwy domeny podstawowej konta w żądaniu operacji Pobierz wszystkich użytkowników w domenie. Odpowiedź zawiera wartość customerId.

Właściwości żądań i odpowiedzi znajdziesz w dokumentacji API.

W tym przykładzie administrator konta prosi wszystkich usuniętych użytkowników na koncie: 

GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&showDeleted=true

Odpowiedź JSON

Pomyślna odpowiedź zwraca kod stanu HTTP 200. Oprócz kodu stanu odpowiedź zawiera też wszystkich użytkowników konta usuniętych w ciągu ostatnich 20 dni: 

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "[email protected]"
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "[email protected]"
  }
 ],
 "nextPageToken": "token for next page of deleted users"
}

Pobieranie zdjęcia użytkownika

Interfejs API pobiera jedną miniaturę zdjęcia, czyli najnowsze zdjęcie profilowe w Google. Aby pobrać ostatnie zdjęcie użytkownika, użyj żądania GET i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. userKey może być podstawowym adresem e-mail użytkownika, adresem użytkownika id lub dowolnym z aliasów adresów e-mail użytkownika. Właściwości żądań i odpowiedzi znajdziesz w dokumentacji API. 

GET https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

W tym przykładzie zwracane jest najnowsze zdjęcie [email protected]:

GET https://admin.googleapis.com/admin/directory/v1/users/[email protected]/photos/thumbnail

Odpowiedź JSON

Pomyślna odpowiedź zwraca kod stanu HTTP 200. 

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "[email protected]",
 "mimeType": "the photo mime type",
 "height": "the photo height in pixels",
 "width": "the photo width in pixels",
 "photoData": "web safe base64 encoded photo data"
}

Kodowanie base64 zdjęć w interfejsie API jest bezpieczne dla sieci i podobny do standardu RFC 4648 „base64url”. Oznacza to, że:

  • Znak ukośnik (/) jest zastępowany znakiem podkreślenia (_).
  • Znak plusa (+) jest zastępowany znakiem łącznika (-).
  • Znak równości (=) jest zastępowany gwiazdką (*).
  • Do wypełnienia używana jest kropka (.), a nie definicja baseURL z normy RFC-4648, która używa znaku równości (=) do wypełnienia. Ma to na celu uproszczenie analizowania adresów URL.
  • Niezależnie od rozmiaru przesyłanego zdjęcia interfejs API zmniejsza go proporcjonalnie do 96 x 96 pikseli.

Jeśli chcesz utworzyć zgodne linki z JavaScriptu, biblioteka Google Closure zawiera funkcje kodowania i dekodowania Base64, które są udostępniane na licencji Apache.

Pobieranie użytkownika jako użytkownik niebędący administratorem

Konta użytkowników mogą modyfikować tylko administratorzy, ale każdy użytkownik w domenie może odczytać profile użytkowników. Użytkownik, który nie jest administratorem, może wysłać żądanie users.get lub users.list z parametrem viewType równym domain_public, aby pobrać profil publiczny użytkownika. Zakres https://www.googleapis.com/auth/admin.directory.user.readonly jest idealny do tego przypadku użycia.

Widok domain_public umożliwia użytkownikowi bez uprawnień administracyjnych dostęp do standardowego zestawu podstawowych pól. Podczas definiowania schematu możesz wybrać, czy pole niestandardowe ma być publiczne, czy prywatne.

Aktualizowanie zdjęcia użytkownika

Aby zaktualizować zdjęcie użytkownika, użyj poniższego żądania PUT i dołącz autoryzację opisaną w artykule Autoryzowanie żądań. userKey może być podstawowym adresem e-mail użytkownika, adresem użytkownika id lub dowolnym z adresów e-mail aliasów użytkownika. Właściwości żądań i odpowiedzi znajdziesz w dokumentacji API. 

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

W tym przykładzie zdjęcie [email protected] zostało zaktualizowane: 

PUT https://admin.googleapis.com/admin/directory/v1/users/[email protected]/photos/thumbnail
 
{
"photoData": "web safe base64 encoded photo data"
}

Podczas aktualizowania zdjęcia interfejs API ignoruje parametry height i width.

Odpowiedź JSON

Pomyślna odpowiedź zwraca kod stanu HTTP 200. 

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "[email protected]",
 "mimeType": "the photo mime type",
 "height": "the photo height in pixels",
 "width": "the photo width in pixels",
 "photoData": "web safe base64 encoded photo data"
}

Usuwanie zdjęcia użytkownika

Aby usunąć zdjęcie użytkownika, użyj poniższego żądania DELETE i dołącz autoryzację opisaną w artykule Autoryzowanie żądań. userKey może być podstawowym adresem e-mail użytkownika, adresem użytkownika id lub dowolnym z adresów e-mail aliasów użytkownika. Właściwości żądań i odpowiedzi znajdziesz w dokumentacji API. 

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

Po usunięciu zdjęcia użytkownika nie będzie ono widoczne. Wszędzie tam, gdzie wymagane jest zdjęcie użytkownika, będzie wyświetlana sylwetka.

Usuwanie konta użytkownika

Aby usunąć konto użytkownika, użyj podanego poniżej żądania DELETE i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. Wartością userKey może być podstawowy adres e-mail użytkownika, unikalny identyfikator użytkownika id lub jeden z aliasów adresów e-mail użytkownika. Właściwości żądań i odpowiedzi znajdziesz w dokumentacji API. 

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey

W tym przykładzie konto użytkownika [email protected] zostało usunięte: 

DELETE https://admin.googleapis.com/admin/directory/v1/users/[email protected]

Pomyślna odpowiedź zwraca tylko kod stanu HTTP 200.

Ważne kwestie, które należy wziąć pod uwagę przed usunięciem użytkownika:

  • Użytkownik, którego konto zostało usunięte, nie będzie już mógł się zalogować.
  • Więcej informacji o usuwaniu kont użytkowników znajdziesz w Centrum pomocy administracyjnej.

przywracanie usuniętego konta użytkownika.

Aby móc przywrócić konto użytkownika usunięte w ciągu ostatnich 20 dni, musisz spełnić określone warunki.

Aby przywrócić konto użytkownika, użyj tego żądania POST i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. Wartość userKey to unikalny użytkownik id znaleziony w odpowiedzi na operację Pobieranie użytkowników usuniętych w ciągu ostatnich 20 dni. Podstawowego adresu e-mail użytkownika lub jednego z jego aliasów adresów e-mail nie można użyć w userKey w przypadku tej operacji. Właściwości żądań i odpowiedzi znajdziesz w dokumentacji API. 

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/undelete

W tym przykładzie użytkownik [email protected] nie został usunięty. Wszystkie właściwości poprzedniego konta tego użytkownika zostaną przywrócone: 

POST https://admin.googleapis.com/admin/directory/v1/users/12309329403209438205/undelete

Pomyślna odpowiedź zwraca tylko kod stanu HTTP 204. Aby wyświetlić konto użytkownika, który nie został usunięty, użyj operacji Pobieranie użytkownika.