Управление пользовательскими полями пользователя

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

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

После определения схемы пользовательские поля ведут себя так же, как и стандартные поля. Вы можете задавать их при обновлении пользователей в вашем домене , получать их с помощью users.get и users.list , а также выполнять поиск по пользовательским полям.

Настройка пользовательских полей в профиле пользователя

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

"customSchemas": {
  "schema1": {
    "field1": "value1",
    "field2": [
      { "value": "value2a" },
      { "value": "value2b" },
      ...
    ],
    ...
  },
  "schema2": {
    "field3": "value3",
    ...
  },
  ...
}

Пользовательские поля с одним значением задаются в виде простых пар ключ-значение, например, "field1": "value1" . Пользовательские поля с несколькими значениями задаются в виде массивов объектов, как стандартные многозначные поля в API, такие как addresses и phones . Эти объекты-значения поддерживают следующие ключи:

Ключи
value Необходимо указать значение, которое нужно сохранить.
type Тип значения, необязательный параметр. Возможные значения:
  • custom
  • home
  • other
  • work
customType Пользовательский тип значения, необязательный. Необходимо использовать, если type задан как custom .

Если пользовательское поле в схеме не указано во время обновления, оно остается без изменений. Если сама схема не указана в customFields во время обновления, все пользовательские поля в этой схеме остаются без изменений. Чтобы удалить пользовательское поле или пользовательскую схему из профиля, необходимо явно установить для них значение null :

"schema1": {
  "field1": null // deletes field1 from this profile.
}

JSON-запрос

В приведенном ниже примере вызов обновляет данные пользователя и устанавливает значения для пользовательской схемы employmentData :

PATCH https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

{
  "customSchemas": {
    "employmentData": {
      "employeeNumber": "123456789",
      "jobFamily": "Engineering"
      "location": "Atlanta",
      "jobLevel": 8,
      "projects": [
        { "value": "GeneGnome" },
        { "value": "Panopticon", "type": "work" },
        { "value": "MegaGene", "type": "custom", "customType": "secret" }
      ]
    }
  }
}

Чтение пользовательских полей в профиле пользователя

Вы можете получить доступ к пользовательским полям в профиле пользователя, установив параметр projection в запросе users.get или users.list в значение custom или full .

Поиск по пользовательским полям в профиле пользователя

Вы можете осуществлять поиск по пользовательским полям, используя параметр query в запросе users.list . Запрос пользовательского поля осуществляется с помощью синтаксиса schemaName.fieldName . Например:

employmentData.projects:"GeneGnome"

Возвращает всех сотрудников, работающих над проектом GeneGnome. Запрос

employmentData.location="Atlanta" employmentData.jobLevel>=7

Возвращает всех сотрудников в Атланте, занимающих должности выше 7-го уровня. Для получения дополнительной информации см. раздел «Поиск пользователей» .

Создайте пользовательскую схему пользователя.

Пользовательскую схему можно добавить во все домены вашей учетной записи Google Workspace. Чтобы создать пользовательскую схему в ваших доменах, используйте следующий POST запрос и включите авторизацию, описанную в разделе «Авторизация запросов» . Свойства строки запроса см. в справочнике API .

POST https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas

Для выполнения всех запросов на создание требуется предоставить необходимую информацию. Если вы используете клиентские библиотеки, они преобразуют объекты данных из выбранного вами языка в объекты в формате JSON.

JSON-запрос

В приведенном ниже примере показан запрос на создание пользовательской схемы. Полный список свойств запроса и ответа см. в справочнике API .

{
  "schemaName": "employmentData",
  "fields": [
    {
      "fieldName": "EmployeeNumber",
      "fieldType": "STRING",
      "multiValued": "false"
    },
    {
      "fieldName": "JobFamily",
      "fieldType": "STRING",
      "multiValued": "false"
    }
  ]
}

В случае успешного ответа возвращается код состояния HTTP 201 , а также свойства новой пользовательской схемы.

Ограничения пользовательской схемы

  • Максимальное количество пользовательских схем, разрешенных в учетной записи, составляет 100.
  • Максимальное количество пользовательских полей, разрешенных в учетной записи, составляет 100.
  • Максимальное количество символов, разрешенное в string поле для пользовательского поля с одним значением, составляет 500. Для пользовательских полей с несколькими значениями количество разрешенных элементов зависит от размера присвоенных значений. Например, можно добавить 150 значений по 100 символов каждое или 50 значений по 500 символов каждое.
  • В пользовательских схемах и именах полей разрешены следующие символы: буквенно-цифровые символы, символы подчеркивания ( _ ) и дефисы ( - ).
  • Изменение типа поля не допускается.
  • Однозначное поле может быть преобразовано в многозначное, но обратная операция не допускается.
  • Переименовать пользовательские схемы или поля невозможно.

Обновить пользовательскую схему

Для обновления пользовательской схемы используйте следующий PUT запрос и включите авторизацию, описанную в разделе «Авторизация запросов» . В schemaKey можно использовать имя схемы или уникальный id схемы. Свойства запроса и ответа см. в справочнике API .

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey

JSON-запрос

В приведенном ниже примере схема employmentData изначально содержала поле JobFamily . Запрос обновляет employmentData , чтобы она содержала только поле EmployeeNumber :

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer/schemas/employmentData

{
  "kind": "admin#directory#schema",
  "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
  "etag": "\"St7vIdePbbDsQUvvrssynd-6JLg/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
  "schemaName": "employmentData",
  "fields": [
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
      "etag": "\"St7vIdePbbDsQUvvrssynd-6JLg/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
      "fieldType": "STRING",
      "fieldName": "EmployeeNumber",
      "multiValued": "false"
    }
  ]
}

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

В случае успешного ответа возвращается код состояния HTTP 200 , а также обновленный ресурс схемы.

Получить пользовательскую схему

Для получения пользовательской схемы используйте следующий GET запрос и включите авторизацию, описанную в разделе «Авторизация запросов» . В schemaKey можно использовать имя схемы или уникальный id схемы. Свойства запроса и ответа см. в справочнике API .

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey

В случае успешного ответа возвращается код состояния HTTP 200 , а также свойства пользовательской схемы. 

{
  "kind": "admin#directory#schema",
  "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
  "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
  "schemaName": "employmentData",
  "fields": [
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
      "fieldType": "STRING",
      "fieldName": "EmployeeNumber"
    },
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"",
      "fieldType": "STRING",
      "fieldName": "JobFamily"
    }
  ]
}

Получить все пользовательские схемы

Чтобы получить все пользовательские схемы в одной учетной записи, используйте следующий GET запрос и включите авторизацию, описанную в разделе «Авторизация запросов» . Свойства запроса и ответа см. в справочнике API . 

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas

В случае успешного ответа возвращается код состояния HTTP 200 , а также пользовательские схемы для учетной записи. 

{
  "kind": "admin#directory#schemas",
  "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/iJ1eWn5AKuR-xTdwH_2IBlvSSKo\"",
  "schemas": [
    {
      "kind": "admin#directory#schema",
      "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
      "schemaName": "employmentData",
      "fields": [
        {
          "kind": "admin#directory#schema#fieldspec",
          "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
          "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
          "fieldType": "STRING",
          "fieldName": "EmployeeNumber"
        },
        {
          "kind": "admin#directory#schema#fieldspec",
          "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==",
          "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"",
          "fieldType": "STRING",
          "fieldName": "JobFamily"
        }
      ]
    }
  ]
}