Esta página foi traduzida pela API Cloud Translation.

Gerenciar campos de usuário personalizados

Adicione esquemas personalizados do usuário ao domínio para definir campos personalizados para os usuários. É possível usar esses campos para armazenar informações como os projetos em que os usuários trabalham, o local físico, a data de contratação ou o que mais atender às necessidades da sua empresa.

Para começar, crie um ou mais esquemas para definir os campos personalizados que fazem sentido para seu domínio. Você pode especificar alguns atributos, como o nome do campo, o tipo (string, booleano, número inteiro etc.), se os valores são únicos ou múltiplos e se os valores podem ser visualizados por qualquer usuário no domínio ou somente por administradores e pelo usuário associado.

Depois que um esquema é definido, os campos personalizados se comportam como campos padrão. É possível defini-las 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-a ao recurso do usuário. Dentro da 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 padrão de vários valores na API, como addresses e phones. Esses objetos de valor aceitam 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` estiver 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 em si não for especificado em customFields no momento da atualização, todos os campos personalizados dele não serão alterados. Para excluir um campo ou um esquema personalizado de um perfil, é preciso defini-lo 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 nos 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 de 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 solicitação POST a seguir e inclua a autorização descrita em Autorizar solicitações. Para as propriedades da string de consulta da solicitação, veja a Referência da API.

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

Em todas as solicitações de criação, é necessário enviar as informações necessárias para atender a elas. Se você estiver usando bibliotecas de cliente, elas vão converter os objetos de dados da linguagem escolhida em objetos formatados em dados JSON.

Solicitação JSON

O exemplo a seguir mostra uma solicitação para criar um esquema personalizado. Para ver a 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, com as propriedades do novo esquema personalizado.

Limites de esquemas personalizados

O número máximo permitido de esquemas personalizados em uma conta é 100.
O número máximo permitido de campos personalizados em uma conta é 100.
O número máximo de caracteres permitido 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, você pode adicionar 150 valores de 100 caracteres cada ou 50 valores de 500 caracteres cada.
Os caracteres permitidos em esquemas personalizados e nomes de campo são alfanuméricos, sublinhados (_) e hifens (-).
Não é permitido alterar o tipo de um campo.
Um campo de valor único pode passar a ser de vários valores, mas a operação inversa não é permitida.
Não é possível renomear esquemas ou campos personalizados.

Atualizar um esquema de usuário personalizado

Para atualizar um esquema personalizado, use a solicitação PUT a seguir 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 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 às solicitações.

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

Recuperar um esquema de usuário personalizado

Para recuperar um esquema personalizado, use a solicitação GET a seguir 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"
    }
  ]
}

Recuperar todos os esquemas personalizados do usuário

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