Gerenciar atributos

Esta página se aplica à Apigee e à Apigee híbrida.

Visão geral

Pense no atributo como os metadados de um recurso. Por exemplo, no caso de um recurso de API, ela pode ter um atributo chamado Target Users que especifica se a API é destinada a consumo público, particular ou interno. Há muitos outros atributos disponíveis.

Os atributos são úteis para você das seguintes maneiras:

É possível filtrar os resultados das pesquisas de recursos com base em atributos. Portanto, com mais atributos, fica mais fácil restringir os resultados das pesquisas.
Você pode criar atributos personalizados e associá-los aos recursos do hub da API.

O hub da API armazena um atributo no formato de chave-valor, em que a chave é o nome do atributo e o valor é o valor correspondente do atributo. E o valor pode estar em qualquer um destes formatos:

String
Enum
JSON

Os atributos podem ser destes dois tipos:

Atributos do sistema, que são predefinidos pelo hub da API.
Atributos do usuário, que são definidos por você.

Atributos do sistema

Os atributos do sistema são predefinidos pelo hub da API para cada tipo de recurso. A lista desses atributos e as definições dos valores deles podem mudar conforme a versão do hub da API. Veja alguns exemplos de atributos do sistema: estágio do ciclo de vida, conformidade da API, credenciamento da API, SLO e assim por diante. Esses atributos podem ser obrigatórios ou opcionais para um recurso. Se um atributo for obrigatório para um recurso, você precisará definir o valor dele ao registrar o recurso.

Os valores de atributos do sistema do tipo Enum podem ser imutáveis ou mutáveis.

Imutável: não é possível fazer alterações nos valores existentes. No entanto, é possível adicionar novos valores mutáveis ao atributo. Por exemplo, o atributo oas-version terá os valores 2.1, 3.0 e 3.1. Não é possível atualizar esses valores, mas sim adicionar novos valores personalizados.
Mutável: é possível adicionar, editar ou excluir os valores existentes. Por exemplo, o atributo lifecycle-stage pode ter inicialmente valores como Dev, Stage, UAT ou Prod. É possível editar os valores existentes e adicionar novos.

Ver atributos do sistema

Console

Para ver todos os atributos do sistema, acesse a página Hub da API > Configurações no console do Google Cloud. É possível ver todos os atributos do sistema já existentes na guia Atributos do sistema.

API REST

Para ver todos os atributos do sistema de um recurso, emita uma solicitação GET para a seguinte API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes

Para saber mais sobre a API, consulte ListAttributes.

O exemplo a seguir mostra a chamada de API para encontrar os atributos do sistema de todos os recursos.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-type: application/json" \
-X GET \
https://apihub.googleapis.com/v1/projects/test-project-1/locations/us-central1/attributes?filter=definition_type=SYSTEM_DEFINED

Editar um atributo do sistema do tipo enumerado

É possível executar as seguintes operações para um valor mutável:

Adicionar um novo valor
Atualizar um valor existente
Excluir um valor de atributo existente

Os exemplos nesta seção mostram como atualizar os valores permitidos de um atributo do sistema do tipo enumerado.

Console

Para adicionar um valor a um atributo do sistema, siga estas etapas:

No console do Google Cloud, acesse a página Hub da API > Configurações.
Isso exibe todos os atributos do sistema existentes na seção Atributos do sistema da guia Atributos.
Clique em Editar no atributo ao qual você quer adicionar um valor.
O painel de edição do atributo abre e mostra os valores dos atributos existentes.
Para adicionar um novo valor, clique em Adicionar item e digite o novo valor que você quer.
Observação: para excluir um valor existente, clique em Excluir no valor que você quer remover. A opção Delete é mostrada apenas para os valores que são mutáveis. Portanto, se a opção de excluir não for exibida para um valor, considere que esse valor é imutável.
Clique em Salvar.

API REST

Para atualizar os valores permitidos de um atributo definido pelo sistema do tipo de dados enumerado, emita uma solicitação PATCH para a seguinte API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes/ATTRIBUTE

Para mais informações sobre a API, consulte UpdateAttribute.

O exemplo a seguir mostra a chamada de API para atualizar os valores do atributo Business unit.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"allowed_values": [
{
"id": "bu1",
"display_name": "Business unit 1",
"description": "The API can be used by business unit 1"
},
{
"id": "bu2",
"display_name": "Business unit 2",
"description": "The API can be used by business unit 2"
},
{
"id": "bu3",
"display_name": "Business unit 3",
"description": "The API can be used by business unit 3"
}]}' \
-X PATCH https://apihub.googleapis.com/v1/projects/test-15/locations/us-central1/attributes/system-business-unit?update_mask=allowed_values

É importante entender como o hub da API interpreta o payload da solicitação para a API UpdateAttribute.

Se o valor especificado já existir no payload, o hub da API fará uma verificação dele e, em seguida, substituirá o valor se ele tiver sido atualizado.
Se o valor não estiver disponível no payload, o hub da API interpretará que o valor precisa ser excluído e o excluirá do hub da API.
Se um novo valor estiver disponível no payload, o hub da API adicionará o novo valor ao atributo.

Atributos definidos pelo usuário

Os atributos definidos pelo usuário são definidos com base nos seus requisitos.

Conferir atributos definidos pelo usuário

Console

Para ver todos os atributos do usuário, acesse a página Hub da API > Configurações no console do Google Cloud. É possível conferir todos os atributos do usuário na seção Atributos definidos pelo usuário da guia Atributos.

API REST

Para ver todos os atributos do usuário de um recurso, emita uma solicitação GET para a seguinte API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes

Para saber mais sobre a API, consulte ListAttributes.

O exemplo a seguir mostra a chamada de API para encontrar os atributos do usuário do recurso da API.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-type: application/json" \
-X GET \
https://apihub.googleapis.com/v1/projects/test-project-1/locations/us-central1/attributes?filter=definition_type=USER_DEFINED

Adicionar um novo atributo do usuário

Console

Para adicionar um novo atributo do usuário, siga estas etapas:

No console do Google Cloud, acesse a página Hub da API > Configurações.
Todos os atributos do usuário são exibidos na seção Atributos do usuário da guia Atributos.
Clique em Criar atributo.
O painel Adicionar um novo atributo abre.
Digite os seguintes detalhes:
- ID: digite um identificador exclusivo para o atributo.
  - Quando você deixa o campo em branco, o hub da API gera um ID exclusivo automaticamente.
  - Se você quiser digitar um valor manualmente, verifique se ele é exclusivo em todos os atributos.
- Nome: digite um nome para o atributo.
- Descrição: se quiser, digite uma descrição do atributo.
- Valores máximos permitidos: insira um número de 1 a 20. Essa configuração especifica o número máximo de valores que o atributo pode ter.
- Tipo de recurso: selecione o tipo do recurso.
Para adicionar um novo valor ao tipo enumerado, clique em Adicionar item e digite o novo valor que você quer adicionar.
Observação: para excluir um valor existente, clique em Excluir no valor que você quer remover.
Clique em Salvar.

API REST

Para adicionar um novo atributo do usuário, envie uma solicitação POST para a seguinte API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes?attribute_id=NEW_ATTRIBUTE_NAME

Para mais informações sobre a API, consulte CreateAttribute.

O exemplo a seguir mostra a chamada de API para criar o atributo do usuário attribute-01.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"  \
-d '{
"display_name" : "custom attribute",
"description" : "custom attribute details",
"definition_type" : "USER_DEFINED",
"scope" : "API",
"data_type" : "ENUM",
"allowed_values" : [
{
"id" : "value-1",
"display_name" : "Value 1",
"description" : "Value 1 test description",
"immutable" : false,
},
{
"id" : "value-2",
"display_name" : "Value 2",
"description" : "Value 2 test description",
"immutable" : false,
},
],
"cardinality" : 4,
"mandatory" : false
}' \
-X POST  https://apihub.googleapis.com/v1/projects/test-15/locations/us-central1/attributes?attribute_id=attribute-01

Editar um atributo do usuário

É possível fazer as seguintes edições em um atributo do usuário:

Atualizar o nome do atributo
Adicionar novo valor do atributo
Excluir um valor de atributo existente

Console

Para editar um atributo do usuário, siga estas etapas:

No console do Google Cloud, acesse a página Hub da API > Configurações.
Todos os atributos do usuário existentes são exibidos na seção Atributos do usuário da guia Atributos.
Clique em Editar no atributo que você quer editar.
O painel de edição do atributo abre e mostra os valores dos atributos existentes.
É possível editar o nome, a descrição e os valores máximos permitidos. Para tipos enumerados, é possível adicionar novos valores. Para adicionar um novo valor a um tipo de enumeração, clique em Adicionar item e digite o novo valor que você quer adicionar.
Clique em Salvar.

API REST

Para editar um atributo do usuário, envie uma solicitação PATCH para a seguinte API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes/ATTRIBUTE

Para mais informações sobre a API, consulte UpdateAttribute.

O exemplo a seguir mostra a chamada de API para atualizar o atributo do usuário API Visibility.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "projects/test-15/locations/us-central1/attributes/API Visibility",
    display_name" : "API Visibility Updated", "allowedValues": [
    {
    "id": "internal",
    "displayName": "Internal",
    "description": "The API is visible internally in an organization"
    },
    {
    "id": "external",
    "displayName": "External",
    "description": "The API is visible externally in an organization"
    },
    {
    "id": "public",
    "displayName": "Public",
    "description": "The API is visible public in an organization"
    }
    ]}' \
    -X PATCH https://autopush-apihub.sandbox.googleapis.com/v1/projects/common-dev-15/locations/us-central1/attributes/API Visibility?update_mask=display_name,allowed_values

É importante entender como o hub da API interpreta o payload da solicitação para a API UpdateAttribute.

Se o valor especificado já existir no payload, o hub da API fará uma verificação dele e, em seguida, substituirá o valor se ele tiver sido atualizado.
Se o valor não estiver disponível no payload, o hub da API interpretará que o valor precisa ser excluído e o excluirá do hub da API.
Se um novo valor estiver disponível no payload, o hub da API adicionará o novo valor ao atributo.