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 atenda às suas necessidades comerciais.

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 é de valor único ou múltiplo e se os valores 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 defini-los ao atualizar usuários no seu domínio, buscá-los com users.get e users.list e também pesquisar campos personalizados.

**Observação**: os campos personalizados também podem ser usados pela API Cloud Identity Groups para criar consultas de grupos dinâmicos para definir a associação a grupos. Consulte Como formular e testar uma consulta de associação para mais informações.

Aviso: não use esse recurso para armazenar informações sensíveis de identificação pessoal, como credenciais de conta, números de identificação governamentais, dados de titulares de cartões, dados financeiros de contas, informações de saúde ou outras informações confidenciais.

Definir campos personalizados em um perfil de usuário

Para atualizar ou criar um esquema, crie uma customSchemaspropriedade 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",
    ...
  },
  ...
}

Observação: Cada schemaName precisa ser exclusivo para um cliente. A reutilização de um nome resulta em um erro 409: Entity already exists.

Os campos personalizados de valor único são definidos como pares de chave-valor simples, 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 está definido como custom.

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

"schema1": {
  "field1": null
}

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/[e-mail]

{
  "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 projection parâmetro em uma users.get ou users.list solicitação como custom ou full.

Pesquisar campos personalizados em um perfil de usuário

É possível pesquisar em campos personalizados usando o query parâmetro em uma users.list solicitação. 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

Um esquema de usuário personalizado pode ser adicionado 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 POST solicitação 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/<var>my_customer or customerId</var>/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 de dados JSON.

Solicitação JSON

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

Limites de esquema personalizado

• 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 de 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 transformado em um campo 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 seguinte PUT solicitação e inclua a autorização descrita em Autorizar solicitações. A schemaKey pode ser o nome do esquema ou o id exclusivo do esquema. 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

Observação: a API também aceita a semântica de patch.

Solicitação JSON

No exemplo a seguir, 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, juntamente com o recurso de esquema atualizado.

Recuperar um esquema de usuário personalizado

Para recuperar um esquema personalizado, use a seguinte GET solicitação e inclua a autorização descrita em Autorizar solicitações. A schemaKey pode ser o nome do esquema ou o id exclusivo do esquema. 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, juntamente 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 de usuário personalizados

Para recuperar todos os esquemas personalizados na mesma conta, use a seguinte GET solicitação 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, juntamente 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"
        }
      ]
    }
  ]
}