Esta página foi traduzida pela API Cloud Translation.

Gerenciar campos de usuário personalizados

É possível definir campos personalizados para usuários no seu domínio adicionando esquemas de usuário personalizados ao domínio. Você pode usar esses campos para armazenar informações como os projetos em que os usuários trabalham, os locais físicos, a data de contratação ou qualquer outra coisa que se encaixe nas necessidades da sua empresa.

Para começar, crie um ou mais esquemas para definir os campos personalizados que fazem sentido para seu domínio. É possível especificar vários atributos, como o nome do campo, o tipo (string, booleano, inteiro etc.), se ele tem um ou vários valores e se os valores dele podem ser visualizados por qualquer usuário no seu domínio ou apenas por administradores e pelo usuário associado.

Depois que um esquema é definido, os campos personalizados se comportam como campos padrão. É possível definir esses campos ao atualizar usuários no seu domínio, buscá-los com users.get e users.list e também pesquisar campos personalizados.

Definir campos personalizados em um perfil de usuário

Para atualizar ou criar um esquema, crie uma propriedade customSchemas e adicione ao recurso do usuário. Na propriedade customSchemas, os campos personalizados são agrupados por esquema no formato JSON padrão:

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

Os campos personalizados de valor único são definidos como pares simples de chave-valor, como "field1": "value1". Os campos personalizados de vários valores são definidos como matrizes de objetos, como os campos de vários valores padrão na API, como addresses e phones. Esses objetos de valor são compatíveis com as seguintes chaves:

Chaves
`value`	O valor a ser armazenado, obrigatório.
`type`	Tipo do valor, opcional. Os valores possíveis são: `custom` `home` `other` `work`
`customType`	Tipo personalizado do valor, opcional. Precisa ser usado quando `type` está definido como `custom`.

Se um campo personalizado em um esquema não for especificado no momento da atualização, ele não será alterado. Se um esquema não for especificado em customFields no momento da atualização, todos os campos personalizados nesse esquema não serão alterados. Para excluir um campo ou esquema personalizado de um perfil, defina-o explicitamente como null:

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

Solicitação JSON

A chamada no exemplo abaixo atualiza um usuário e define valores para o esquema personalizado 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" }
      ]
    }
  }
}

Ler campos personalizados em um perfil de usuário

É possível buscar campos personalizados em um perfil de usuário definindo o parâmetro projection em uma solicitação users.get ou users.list para custom ou full.

Pesquisar campos personalizados em um perfil de usuário

É possível pesquisar em campos personalizados usando o parâmetro query em uma solicitação users.list. Você solicita o campo personalizado com uma sintaxe schemaName.fieldName. Exemplo:

employmentData.projects:"GeneGnome"

retorna todos os funcionários que trabalham no projeto GeneGnome. A consulta

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

retorna todos os funcionários em Atlanta acima do nível de trabalho 7. Para mais informações, consulte Pesquisar usuários.

Criar um esquema de usuário personalizado

É possível adicionar um esquema de usuário personalizado a todos os domínios da sua conta do Google Workspace. Para criar um esquema de usuário personalizado nos seus domínios, use a seguinte solicitação POST e inclua a autorização descrita em Autorizar solicitações. Para as propriedades da string de consulta de solicitação, consulte a referência da API.

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

Todas as solicitações de criação exigem que você envie as informações necessárias para atender à solicitação. Se você estiver usando bibliotecas de cliente, elas vão converter os objetos de dados do idioma escolhido em objetos formatados por dados JSON.

Solicitação JSON

O exemplo a seguir mostra uma solicitação para criar um esquema personalizado. Para uma lista completa de propriedades de solicitação e resposta, consulte a referência da API.

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

Uma resposta bem-sucedida retorna um código de status HTTP 201, junto com as propriedades do novo esquema personalizado.

Limites de esquemas personalizados

O número máximo de esquemas personalizados permitidos em uma conta é 100.
O número máximo de campos personalizados permitidos em uma conta é 100.
O número máximo de caracteres permitidos em um campo string para um campo personalizado de valor único é 500. Para campos personalizados com vários valores, o número de elementos permitidos depende do tamanho dos valores atribuídos. Por exemplo, é possível adicionar 150 valores de 100 caracteres cada ou 50 valores de 500 caracteres cada.
Os caracteres permitidos em esquemas personalizados e nomes de campos são caracteres alfanuméricos, sublinhados (_) e hifens (-).
Não é permitido mudar o tipo de um campo.
Um campo de valor único pode ser convertido em multivalor, mas a operação inversa não é permitida.
Não é possível renomear campos ou esquemas personalizados.

Atualizar um esquema de usuário personalizado

Para atualizar um esquema personalizado, use a seguinte solicitação PUT e inclua a autorização descrita em Autorizar solicitações. O schemaKey pode ser o nome do esquema ou o esquema exclusivo id. Para as propriedades de solicitação e resposta, consulte a referência da API.

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

Solicitação JSON

No exemplo abaixo, o esquema employmentData continha um campo JobFamily quando foi criado originalmente. A solicitação está atualizando employmentData para conter apenas um campo 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"
    }
  ]
}

Todas as solicitações de atualização exigem que você envie as informações necessárias para atender à solicitação.

Uma resposta bem-sucedida retorna um código de status HTTP 200, junto com o recurso de esquema atualizado.

Extrair um esquema de usuário personalizado

Para recuperar um esquema personalizado, use a seguinte solicitação GET e inclua a autorização descrita em Autorizar solicitações. O schemaKey pode ser o nome do esquema ou o esquema exclusivo id. Para as propriedades de solicitação e resposta, consulte a referência da API.

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

Uma resposta bem-sucedida retorna um código de status HTTP 200, com as propriedades do esquema personalizado.

{
  "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"
    }
  ]
}

Extrair todos os esquemas de usuário personalizados

Para recuperar todos os esquemas personalizados na mesma conta, use a seguinte solicitação GET e inclua a autorização descrita em Autorizar solicitações.Para as propriedades de solicitação e resposta, consulte a Referência da API.

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

Uma resposta bem-sucedida retorna um código de status HTTP 200, junto com os esquemas personalizados da conta.

{
  "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"
        }
      ]
    }
  ]
}