Interfejs Directory API udostępnia automatyczne metody tworzenia, aktualizowania i usuwania użytkowników. Możesz też uzyskać informacje o poszczególnych użytkownikach lub listach użytkowników, którzy spełniają określone kryteria. Poniżej znajdziesz przykłady 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 osobiste konto Gmail zostało przekształcone w firmowe konto e-mail z własną nazwą domeny, nie możesz tworzyć nowych kont użytkowników, dopóki nie odblokujesz dodatkowych ustawień Google Workspace. Więcej informacji znajdziesz w artykule Firmowe konta e-mail w G Suite zostały przekształcone w konta G Suite Basic.
Aby utworzyć konto użytkownika przy użyciu jednej z Twoich domen, użyj tego żądania POST i dołącz autoryzację opisaną w artykule Informacje o uwierzytelnianiu i autoryzacji. Dostępne zakresy interfejsu Directory API możesz wyświetlić na liście zakresów OAuth 2.0. Informacje o właściwościach ciągu zapytania żądania znajdziesz w opisie metody users.insert().
POST https://admin.googleapis.com/admin/directory/v1/users
Wszystkie prośby o utworzenie wymagają przesłania informacji potrzebnych do ich realizacji. Jeśli używasz bibliotek klienta, przekształcają one obiekty danych z wybranego języka w sformatowane obiekty danych JSON.
Żądanie JSON
Poniższy kod JSON przedstawia przykładowe żądanie utworzenia użytkownika. Pełną listę właściwości żądań i odpowiedzi znajdziesz w dokumentacji API.
{ "primaryEmail": "liz@example.com", "name": { "givenName": "Elizabeth", "familyName": "Smith" }, "suspended": false, "password": "new user password", "hashFunction": "SHA-1", "changePasswordAtNextLogin": false, "ipWhitelisted": false, "ims": [ { "type": "work", "protocol": "gtalk", "im": "liz_im@talk.example.com", "primary": true } ], "emails": [ { "address": "liz@example.com", "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ść zapytań dotyczących tworzenia jest zbyt wysoka, możesz otrzymywać z serwera interfejsu API odpowiedzi HTTP 503 wskazujące, że limit został przekroczony. Jeśli otrzymasz takie odpowiedzi, użyj algorytmu wycofywania wykładniczego, aby ponowić żądania.
Warto wiedzieć o nowym koncie:
- Jeśli na koncie Google zakupiono licencje na pocztę, do nowego konta użytkownika automatycznie przypisywana jest skrzynka pocztowa. Przypisanie może potrwać kilka minut, zanim zostanie ukończone i aktywowane.
- Edytowanie w żądaniu pola tylko do odczytu, np.
isAdmin, jest cicho ignorowane przez usługę API. - Maksymalna liczba domen dozwolonych na koncie to 600 (1 domena podstawowa + 599 domen dodatkowych).
- Jeśli podczas tworzenia konta użytkownik nie został 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 ulegnie zmianie. Więcej informacji o strukturach organizacji znajdziesz w Centrum pomocy dla administratorów. Więcej informacji o przenoszeniu użytkownika do innej organizacji znajdziesz w artykule Aktualizowanie użytkownika.
- W przypadku nowych kont użytkowników wymagany jest
password. Jeśli określono wartośćhashFunction, hasło musi być prawidłowym kluczem skrótu. Jeśli nie jest określone, hasło powinno być w formie zwykłego tekstu i mieć od 8 do 100 znaków ASCII. Więcej informacji znajdziesz w dokumentacji 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 finansowy i spowoduje naliczenie opłat na koncie rozliczeniowym klienta. Więcej informacji znajdziesz w informacjach o płatnościach za interfejs API.
- Konto Google Workspace może obejmować dowolne Twoje domeny. Na koncie z wieloma domenami użytkownicy w jednej domenie mogą udostępniać usługi użytkownikom w innych domenach konta. Więcej informacji o użytkownikach w wielu domenach znajdziesz w artykule Informacje o wielu domenach w interfejsie API.
- Mogą występować konta 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ą istnieć konta gości. Jeśli użytkownicy zaproszą do współpracy w usłudze Dysk osoby spoza organizacji, które nie mają kont Google, otrzymają one konta gości w formacie nazwa_użytkownika_gościa@twoja_domena.com. Jeśli dodasz użytkownika o tej samej nazwie co konto gościa, konto zostanie przekształcone w pełne konto Google Workspace. Konto zachowa aktualne uprawnienia do plików na Dysku. Zobacz Udostępnianie dokumentów użytkownikom.
Prawidłowa 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 sekcji Autoryzowanie żądań. userKey może być podstawowym adresem e-mail użytkownika, unikalnym identyfikatorem użytkownika id lub jednym z aliasów adresu e-mail użytkownika.
PUT https://admin.googleapis.com/admin/directory/v1/users/userKey
Treść żądania i odpowiedzi zawiera instancję obiektu
User. Interfejs Directory API obsługuje jednak semantykę poprawki, więc w żądaniu musisz przesłać tylko zaktualizowane pola.
Przykładowe żądanie
W poniższym przykładzie imię użytkownika givenName to „Elizabeth”, a podczas tworzenia konta podano tylko służbowy adres e-mail.
{
"name": {
"givenName": "Elizabeth",
"familyName": "Smith"
},
"emails": [
{
"address": "liz@example.com",
"type": "work",
"primary": true
}
]
}
Poniższa prośba zmienia imię givenName z „Elizabeth” na „Liz” i dodaje domowy adres e-mail. Pamiętaj, że oba adresy e-mail są podane w całości, ponieważ pole jest tablicą.
PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com
{
"name": {
"givenName": "Liz",
},
"emails": [
{
"address": "liz@example.com",
"type": "work",
"primary": true
},
{
"address": "liz@home.com",
"type": "home"
}
]
}
Pomyślna odpowiedź zwraca HTTP 200 i 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.
- Wprowadzenie zmiany nazwy konta użytkownika we wszystkich usługach może potrwać do 10 minut.
- Gdy zmienisz nazwę użytkownika, stara nazwa użytkownika zostanie zachowana jako alias, aby zapewnić nieprzerwane dostarczanie poczty w przypadku ustawień przekazywania poczty e-mail. Nie będzie ona dostępna jako nowa nazwa użytkownika.
- Ogólnie zalecamy też, aby nie używać adresu e-mail użytkownika jako klucza do trwałych danych, ponieważ może się on zmienić.
- Pełną listę efektów zmiany nazwy użytkownika w aplikacjach Google Workspace znajdziesz w Centrum pomocy dla administratorów.
Przypisywanie użytkownikowi ról administratora
Aby przekształcić użytkownika w superadministratora, użyj tego żądania POST i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. userKey może być podstawowym adresem e-mail użytkownika, unikalnym identyfikatorem użytkownika id lub jednym z aliasów adresu e-mail użytkownika. Informacje o właściwościach żądań i odpowiedzi znajdziesz w dokumentacji API. Więcej informacji o superadministratorze znajdziesz w Centrum pomocy dotyczącym administracji.
POST https://admin.googleapis.com/admin/directory/v1/users/userKey/makeAdminŻądanie JSON
W tym przykładzie użytkownik, którego userKey to ela@example.com, został superadministratorem:
POST https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/makeAdmin
{
"status": true
}Prawidłowa odpowiedź zwraca kod stanu HTTP 200.
Zarządzanie relacjami użytkowników
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 zwykle używane w przypadku relacji między menedżerem a pracownikiem lub asystentem, ale obsługuje też wiele innych typów relacji. Relacja jest wyświetlana na karcie „Powiązane osoby” użytkownika w dowolnej aplikacji Google Workspace, która obsługuje tę kartę. Przykłady miejsc, w których karta jest widoczna, znajdziesz w artykule Dodawanie informacji do profilu użytkownika w katalogu.
Tworzenie relacji między użytkownikami
Relację można zdefiniować tylko w jednym kierunku, zaczynając od „właściciela”, którego rekord zawiera pole relations. Pole type
opisuje relację innej osoby z użytkownikiem, który jest właścicielem konta. Na przykład w relacji menedżer–pracownik pracownik jest właścicielem konta, a Ty dodajesz do jego konta pole relations typu 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
Pole relations można aktualizować tylko w całości – nie możesz zmieniać typu relacji ani usuwać poszczególnych osób z listy. W przykładzie powyżej, aby usunąć dotychczasową relację z kontem menedżera i ustawić konto menedżera połączone linią przerywaną jako konto menedżera użytkownika będącego właścicielem, zaktualizuj konto użytkownika będącego właścicielem, podając wszystkie wartości pól w nowej postaci.
{
"relations": [
{
"value": "EMAIL_ADDRESS_RELATION_2",
"type": "manager"
}
]
}
Aby usunąć wszystkie relacje użytkownika będącego właścicielem, ustaw wartość relations na pustą:
{
"relations": []
}
Pobieranie użytkownika
Aby pobrać użytkownika, użyj poniższego żądania GET i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. userKey może być podstawowym adresem e-mail użytkownika, unikalnym identyfikatorem użytkownika id lub jednym z aliasów adresu e-mail użytkownika. Informacje o właściwościach żądań i odpowiedzi znajdziesz w dokumentacji API.
GET https://admin.googleapis.com/admin/directory/v1/users/userKeyTen przykład zwraca właściwości konta użytkownika, którego podstawowy adres e-mail lub alias to liz@example.com:
GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com
Odpowiedź JSON
Prawidłowa odpowiedź zwraca kod stanu HTTP 200. Oprócz kodu stanu odpowiedź zawiera właściwości konta użytkownika.
{ "kind": "directory#user", "id": "the unique user id", "primaryEmail": "liz@example.com", "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": "lizim@talk.example.com", "primary": true } ], "emails": [ { "address": "liz@example.com", "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": [ "lizsmith@example.com", "lsmith@example.com" ], "nonEditableAliases": [ "liz@test.com" ], "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 poniższego żądania GET i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. Aby ułatwić czytanie, w tym przykładzie użyto znaków ł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*
Informacje o właściwościach żądań i odpowiedzi znajdziesz w dokumentacji API.
Odpowiedź JSON
W tym przykładzie zwracani są wszyscy użytkownicy w domenie example.com, przy czym na stronie odpowiedzi może się znajdować maksymalnie 2 domeny użytkowników. W tej odpowiedzi znajduje się nextPageToken dla kolejnej listy użytkowników. Domyślnie system zwraca listę 100 użytkowników w kolejności alfabetycznej adresów e-mail:
GET https://admin.googleapis.com/admin/directory/v1/users?domain=example.com&maxResults=2
Prawidłowa odpowiedź zwraca kod stanu HTTP 200. Oprócz kodu stanu odpowiedź zawiera 2 konta użytkowników w domenie example.com (maxResults=2):
{ "kind": "directory#users", "users": [ { "kind": "directory#user", "id": "the unique user id", "primaryEmail": "liz@example.com", "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": "lizim@talk.example.com", "primary": true } ], "emails": [ { "address": "liz@example.com", "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": [ "lizsmith@example.com", "lsmith@example.com" ], "nonEditableAliases": [ "liz@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "corp/engineering", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "user unique ID", "primaryEmail": "admin2@example.com", "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": "admin2@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "contractor license number", "type": "custom", "customType": "work" } ], "aliases": [ "second_admin@example.com" ], "nonEditableAliases": [ "admin@test.com" ], "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 poniższego żądania GET i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. Aby ułatwić czytanie, w tym przykładzie użyto znaków ł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
customerto wartośćmy_customerlubcustomerId. - Użyj ciągu znaków
my_customer, aby przedstawićcustomerIdna swoim koncie. - Jako administrator sprzedawcy użyj
customerIdklienta, któremu sprzedano usługę. W przypadkucustomerIdw żądaniu operacji Pobieranie wszystkich kont użytkowników w domenie użyj nazwy domeny podstawowej konta. Odpowiedź zawiera wartośćcustomerId. - Opcjonalny ciąg zapytania
orderByokreśla, czy lista jest sortowana według podstawowego adresu e-mail użytkownika, nazwiska czy imienia. Gdy używaszorderBy, możesz też użyć ciągu zapytaniasortOrder, aby wyświetlić wyniki w kolejności rosnącej lub malejącej. - Opcjonalny ciąg zapytania
queryumożliwia wyszukiwanie w wielu polach profilu użytkownika, w tym w polach podstawowych i niestandardowych. Przykłady znajdziesz w artykule Wyszukiwanie użytkowników.
Informacje o właściwościach żądań i odpowiedzi znajdziesz w dokumentacji API.
W tym przykładzie administrator konta prosi o zwrócenie wszystkich użytkowników na koncie z jednym wpisem użytkownika 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 wysyła prośbę o wszystkich użytkowników na odsprzedanym koncie, które ma wartość customerId równą C03az79cb.
GET https://admin.googleapis.com/admin/directory/v1/users?customer=C03az79cb&maxResults=1
Odpowiedź JSON
Prawidłowa odpowiedź zwraca kod stanu HTTP 200. Oprócz kodu stanu odpowiedź zawiera wszystkich użytkowników na tym koncie:
{ "kind": "directory#users", "users": [ { "kind": "directory#user", "id": "the unique user id", "username": "admin2@example.com", "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": "admin2@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "aliases": [ "second_admin@example.com" ], "nonEditableAliases": [ "another_admin@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "liz@example.com", "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": "liz@example.com", "type": "home", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "bank" } ], "relations": [ { "value": "liz", "type": "friend", "customType": "" } ], "aliases": [ "lizsmith@example.com", "lsmith@example.com" ], "nonEditableAliases": [ "liz@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "test3@example.com", "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": "test@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "aliases": [ "tester3@example.com" ], "nonEditableAliases": [ "third@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "work_admin@example.com", "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": "work_admin@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "aliases": [ "my_alias@example.com" ], "nonEditableAliases": [ "other_alias@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true } ], "nextPageToken": "NNNNN" }
Przywracanie ostatnio usuniętych kont użytkowników
Aby pobrać wszystkich użytkowników usuniętych w ciągu ostatnich 20 dni z konta lub z jednej z domen konta, użyj tych żądań GET i dołącz autoryzację opisaną w artykule Autoryzowanie żądań. Aby przywrócić usunięte konto użytkownika, przeczytaj artykuł Przywracanie usuniętego konta użytkownika.
Aby pobrać użytkowników usuniętych w ciągu ostatnich 20 dni z domeny głównej konta lub subdomeny, użyj tego GET żądania. Ciąg zapytania domain to nazwa domeny podstawowej. Informacje o właściwościach żądań i odpowiedzi użytkownika znajdziesz w dokumentacji API. Aby można było łatwiej czytać, w tym przykładzie użyto znaków ł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 &showDeleted=true
GET. Aby ułatwić czytanie, w tym przykładzie użyto znaków ł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
customerto wartośćmy_customerlubcustomerId. - Jako administrator konta używaj ciągu znaków
my_customer, aby reprezentowaćcustomerIdna swoim koncie. - Jako administrator sprzedawcy użyj
customerIdklienta, któremu sprzedano usługę. W przypadkucustomerIdw żądaniu operacji Pobieranie wszystkich kont użytkowników w domenie użyj nazwy domeny podstawowej konta. Odpowiedź zawiera wartośćcustomerId.
Informacje o właściwościach żądań i odpowiedzi znajdziesz w dokumentacji API.
W tym przykładzie administrator konta prosi o wszystkich usuniętych użytkowników na koncie:
GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&showDeleted=true
Odpowiedź JSON
Prawidłowa 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": "user1@example.com" }, { "kind": "directory#user", "id": "the unique user id", "primaryEmail": "user3@example.com" } ], "nextPageToken": "token for next page of deleted users" }
Pobieranie zdjęcia użytkownika
Interfejs API pobiera miniaturę zdjęcia, czyli najnowsze zdjęcie profilowe Google. Aby pobrać najnowsze zdjęcie użytkownika, użyj tego żądania GET i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. userKey może być podstawowym adresem e-mail użytkownika, id lub dowolnym z aliasów e-mail użytkownika. Informacje o właściwościach żądań i odpowiedzi znajdziesz w dokumentacji API.
GET https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnailW tym przykładzie zwracane jest najnowsze zdjęcie użytkownika liz@example.com:
GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail
Odpowiedź JSON
Prawidłowa odpowiedź zwraca kod stanu HTTP 200.
{ "kind": "directory#user#photo", "id": "the unique user id", "primaryEmail": "liz@example.com", "mimeType": "the photo mime type", "height": "the photo height in pixels", "width": "the photo width in pixels", "photoData": "web safe base64 encoded photo data" }
Bezpieczne dla sieci kodowanie base64 zdjęć w interfejsie API jest podobne do RFC 4648 „base64url”. Oznacza to, że:
- Ukośnik (/) jest zastępowany znakiem podkreślenia (_).
- Znak plusa (+) jest zastępowany łącznikiem (-).
- Znak równości (=) jest zastępowany gwiazdką (*).
- W przypadku dopełniania zamiast definicji RFC-4648 baseURL, która używa znaku równości (=), używany jest znak kropki (.). Upraszcza to analizowanie adresów URL.
- Niezależnie od rozmiaru przesyłanego zdjęcia interfejs API zmniejsza je proporcjonalnie do 96 x 96 pikseli.
Jeśli musisz utworzyć zgodne linki w JavaScript, biblioteka Google Closure zawiera funkcje kodowania i dekodowania Base64, które są udostępniane na licencji Apache.
Pobieranie użytkownika jako osoby niebędącej administratorem
Konta użytkowników mogą być modyfikowane tylko przez administratorów, ale każdy użytkownik w domenie może odczytywać profile użytkowników. Użytkownik bez uprawnień administratora 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 w tym przypadku użycia.
Widok domain_public umożliwia użytkownikowi bez uprawnień administratora dostęp do standardowego zestawu podstawowych pól. W przypadku pola niestandardowego możesz określić, czy ma być publiczne czy prywatne, podczas definiowania schematu.
Aktualizowanie zdjęcia użytkownika
Aby zaktualizować zdjęcie użytkownika, użyj tego żądania PUT i dołącz autoryzację opisaną w artykule Autoryzowanie żądań. userKey może być podstawowym adresem e-mail użytkownika, id lub dowolnym adresem e-mail aliasu użytkownika. Informacje o właściwościach żądań i odpowiedzi znajdziesz w dokumentacji API.
PUT https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnailW tym przykładzie zdjęcie liz@example.com zostało zaktualizowane:
PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail
{
"photoData": "web safe base64 encoded photo data"
}Podczas aktualizowania zdjęcia interfejs API ignoruje zasady height i width.
Odpowiedź JSON
Prawidłowa odpowiedź zwraca kod stanu HTTP 200.
{ "kind": "directory#user#photo", "id": "the unique user id", "primaryEmail": "liz@example.com", "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 tego żądania DELETE i dołącz autoryzację opisaną w artykule Autoryzowanie żądań. userKey może być podstawowym adresem e-mail użytkownika, id lub dowolnym adresem e-mail aliasu użytkownika. Informacje o właściwościach żądań i odpowiedzi znajdziesz w dokumentacji API.
DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnailPo usunięciu zdjęcie użytkownika nie jest wyświetlane. W miejscach, w których wymagane jest zdjęcie użytkownika, będzie wyświetlana sylwetka.
Usuwanie konta użytkownika
Aby usunąć konto użytkownika, użyj poniższego żądania DELETE i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. userKey może być podstawowym adresem e-mail użytkownika, unikalnym identyfikatorem użytkownika id lub jednym z aliasów adresu e-mail użytkownika. Informacje o właściwościach żądań i odpowiedzi znajdziesz w dokumentacji API.
DELETE https://admin.googleapis.com/admin/directory/v1/users/userKeyW tym przykładzie usunięto konto użytkownika ela@example.com:
DELETE https://admin.googleapis.com/admin/directory/v1/users/liz@example.com
Pomyślna odpowiedź zwraca tylko kod stanu HTTP 200.
Ważne kwestie, które należy wziąć pod uwagę przed usunięciem użytkownika:
- Usunięty użytkownik nie będzie już mógł się logować.
- Więcej informacji o usuwaniu kont użytkowników znajdziesz w Centrum pomocy dla administratorów.
Przywracanie konta użytkownika
Użytkownik usunięty w ciągu ostatnich 20 dni musi spełnić określone warunki, aby można było przywrócić jego konto.
Aby przywrócić konto użytkownika, użyj poniższego żądania POST i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. 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 ani jednego z aliasów adresu e-mail nie można użyć w polu userKey w przypadku tej operacji. Informacje o właściwościach żądań i odpowiedzi znajdziesz w dokumentacji API.
POST https://admin.googleapis.com/admin/directory/v1/users/userKey/undeleteW tym przykładzie użytkownik ela@example.com zostanie przywrócony. Wszystkie poprzednie usługi na koncie 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 nieusuniętego użytkownika, użyj operacji Pobieranie użytkownika.