Эта страница переведена с помощью Cloud Translation API.

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

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

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

После определения схемы настраиваемые поля ведут себя так же, как стандартные поля. Вы можете установить их при обновлении пользователей в вашем домене , получать их с 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"
        }
      ]
    }
  ]
}