Управление группами

На этой странице рассказывается, как управлять группами Google с помощью Directory API:

  • Создать группу
  • Обновить группу
  • Добавить псевдоним группы
  • Получить группу
  • Получить все группы для домена или учетной записи
  • Получить все группы для участника
  • Получить все псевдонимы групп
  • Удаление псевдонима группы
  • Удалить группу

Создать группу

Чтобы создать группу, используйте следующий запрос POST и включите авторизацию, описанную в разделе «Авторизация запросов» . Вы можете создать группу для любого домена, связанного с учетной записью. Информацию о строках запроса, свойствах запроса и ответа см. в методе groups.insert .

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

Следующий запрос JSON показывает пример тела запроса, который создает группу. Адрес электронной почты группы: sales_group@example.com:

{
   "email": "sales_group@example.com",
   "name": "Sales Group",
   "description": "This is the Sales group."
}

Успешный ответ возвращает код состояния HTTP 201 и свойства новой группы.

Обновить группу

Чтобы обновить настройки группы, используйте следующий запрос PUT и включите авторизацию, описанную в разделе Авторизация запросов . groupKey — это адрес электронной почты группы, адрес электронной почты любого псевдонима группы или уникальный id группы. Информацию о строках запроса, свойствах запроса и ответа см. в методе groups.update .

PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey 

В целом Google рекомендует не использовать адрес электронной почты группы в качестве ключа для постоянных данных, поскольку адрес электронной почты может быть изменен.

В следующем примере уникальный groupKeynnn , а имя группы — APAC Sales Group:

PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn
{
    "email": "sales_group@example.com",
    "name": "APAC Sales Group"
}

Для запроса на обновление вам нужно только предоставить обновленную информацию в своем запросе. Вам не нужно вводить в запрос все свойства группы.

Успешный ответ возвращает код состояния HTTP 201 и свойства новой группы:

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "sales_group@example.com",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "best_sales_group@example.com"
     }
    ],
    "nonEditableAliases: [
     {
        "alias": "liz@test.com"
     }
    ]
}

Добавить псевдоним группы

Чтобы добавить псевдоним группы, используйте следующий запрос POST и включите авторизацию, описанную в разделе Авторизация запросов . groupKey — это адрес электронной почты группы, адрес электронной почты любого псевдонима группы или уникальный id группы. Строки запроса, свойства запроса и ответа см. в ресурсе groups .

POST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

В целом Google рекомендует не использовать адрес электронной почты группы в качестве ключа для постоянных данных, поскольку адрес электронной почты может быть изменен.

В следующем запросе JSON показан пример запроса на создание псевдонима группы. groupKey — это уникальный id группы, представленный NNNN

POST https://admin.googleapis.com/admin/directory/v1/groups/NNNN/aliases
{
    "alias": "best_sales_group@example.com"
}

Успешный ответ возвращает код состояния HTTP 201 и свойства нового псевдонима группы.

Получить группу

Чтобы получить группу, используйте следующий запрос GET и включите авторизацию, описанную в разделе «Авторизация запросов» . groupKey — это адрес электронной почты группы, адрес электронной почты любого псевдонима группы или уникальный id группы. Информацию о строках запроса, свойствах запроса и ответа см. в методе groups.get .
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey

В целом Google рекомендует не использовать адрес электронной почты группы в качестве ключа для постоянных данных, поскольку адрес электронной почты может быть изменен.

В следующем примере уникальный идентификатор groupKeynnnn :

GET https://admin.googleapis.com/admin/directory/v1/groups/nnnn

Успешный ответ возвращает код состояния HTTP 200 и настройки группы:

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "sales_group@example.com",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "best_sales_group@example.com"
     }
    ],
    "nonEditableAliases: [
     {
        "alias": "liz@test.com"
     }
    ]
}

Получить все группы для домена или учетной записи

Чтобы получить все группы для определенного домена или учетной записи, используйте следующий запрос GET и включите авторизацию, описанную в разделе «Авторизация запросов» . Информацию о строках запроса, свойствах запроса и ответа см. в методе groups.list . Для удобства чтения в этом примере используются возвраты строк:

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=domain name
&customer=my_customer or customerId&pageToken=pagination token
&maxResults=max results

При получении всех групп для домена или учетной записи учитывайте следующее:

  • Все группы для субдомена: используйте аргумент domain с именем домена.
  • Все группы для учетной записи: используйте аргумент customer со значением my_customer или значением customerId учетной записи. Как администратор учетной записи, используйте строку my_customer для представления customerId вашей учетной записи. Если вы являетесь реселлером и имеете доступ к учетной записи перепродаваемого клиента, используйте customerId перепродаваемой учетной записи. В качестве значения customerId используйте основное доменное имя учетной записи в запросе операции «Получить всех пользователей в домене ». Результирующий ответ имеет значение customerId .
  • Использование аргументов domain и customer : API каталога возвращает все группы для domain .
  • Не использовать аргументы domain и customer : API каталога возвращает все группы для учетной записи, связанной с my_customer . Это customerId учетной записи администратора, сделавшего запрос.
  • Использование аргументов customer и userKey : API каталога возвращает ошибку. Вы должны сделать два отдельных запроса с этими аргументами.

В следующем примере администратор учетной записи использует my_customer для запроса списка всех групп учетной записи:

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=my_customer&maxResults=2

В следующем примере запрос администратора реселлера возвращает все группы для перепроданной учетной записи с customerId C03az79cb . Максимальное количество результатов, возвращаемых на страницу ответа, — 2. В этом ответе имеется nextPageToken для следующего списка пользователей:

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=C03az79cb&maxResults=2

В случае успешного ответа возвращается код состояния HTTP 200 и группы в алфавитном порядке группового электронного письма:

{
"kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "support@sales.com",
      "name": "Sales support",
      "directMembersCount": "6",
      "description": "The sales support group",
      "adminCreated": true
     },
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "travel@sales.com",
      "name": "Sales travel",
      "directMembersCount": "2",
      "description": "The travel group supporting sales",
      "adminCreated": false,
      "aliases": [
       {
         "alias": "best_sales_group@example.com"
       }
      ],
      "nonEditableAliases: [
       {
         "alias": "liz@test.com"
       }
      ]
     },
  "nextPageToken": "NNNN"
  }

Получить все группы для участника

Чтобы получить все группы, на которые у участника есть подписка, используйте следующий запрос GET и включите авторизацию, описанную в разделе Авторизация запросов . Для удобства чтения в этом примере используются возвраты строк:

GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=user key
?pageToken=pagination token
&maxResults=maximum results per response page
  • Участник может быть либо пользователем, либо группой.
  • userKey может быть основным адресом электронной почты пользователя, псевдонимом адреса электронной почты пользователя, основным адресом электронной почты группы, псевдонимом электронной почты группы или уникальным id пользователя, который можно найти с помощью операции Получить пользователя .
  • Пользователь или группа, указанные в userKey должны принадлежать вашему домену.
  • Используйте строку запроса pageToken для ответов с большим количеством групп. В случае нумерации страниц ответ возвращает свойство nextPageToken , которое дает токен для следующей страницы результатов ответа. Ваш следующий запрос использует этот токен в качестве значения строки запроса pageToken .
  • Использование аргументов customer и userKey : API каталога возвращает ошибку. Вы должны сделать два отдельных запроса с этими аргументами.

Свойства запроса и ответа см. в методе groups.list .

Успешный ответ возвращает код состояния HTTP 200 и список информации об участниках:

  • Возвращаются все группы, на которые у участника есть подписка, включая группы за пределами домена пользователя.
  • Группы возвращаются в алфавитном порядке адреса электронной почты каждой группы.
  • В теле ответа id — это уникальный идентификатор группы.
  • В ответе список группы, находящейся за пределами домена пользователя, не включает псевдонимы внешней группы.
{
    "kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "sales_group@example.com",
      "name": "sale group",
      "directMembersCount": "5",
      "description": "Sales group"
     },
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "support_group.com",
      "name": "support group",
      "directMembersCount": "5",
      "description": "Support group"
     }
  ],
   "nextPakeToken": "NNNNN"
}

Получить все псевдонимы групп

Чтобы получить все псевдонимы группы, используйте следующий запрос GET и включите авторизацию, описанную в разделе Авторизация запросов . groupKey может быть основным адресом электронной почты группы, уникальным id группы или любым из псевдонимов группы. Свойства запроса и ответа смотрите в ресурсе groups .

GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

Успешный ответ возвращает код состояния HTTP 201 и список псевдонимов группы.

Удаление псевдонима группы

Чтобы удалить псевдоним группы, используйте следующий запрос DELETE и включите авторизацию, описанную в разделе «Авторизация запросов» . groupKey может быть основным адресом электронной почты группы, уникальным id группы или любым из псевдонимов группы. aliasId — это удаляемый псевдоним. Свойства запроса и ответа см. в ресурсе groups :

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases/aliasId

Успешный ответ возвращает код состояния HTTP 201 .

Удалить группу

Чтобы удалить группу, используйте следующий запрос DELETE и включите авторизацию, описанную в разделе «Авторизация запросов» . groupKey — это уникальный id группы:

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey
Например, этот запрос DELETE удаляет группу с id группы nnnn :
DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn

Успешный ответ возвращает код состояния HTTP 200 .

При удалении группы происходит следующее:

  • Все участники группы будут удалены. Учетные записи пользователей участника не удаляются.
  • Архив группы удален.
  • Сообщения, отправленные на адрес удаленной группы, не доставляются. Вместо этого отправитель получает сообщение о возврате.