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.
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.
- É possível associar dados personalizados 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 comoDev
,Stage
,UAT
ouProd
. É 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 valor e digite o novo valor que você quer.
- 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 do usuário
Os atributos do usuário são definidos com base nos seus requisitos.
Ver atributos do 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 ver todos os atributos do usuário na seção Atributos do 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 Adicionar 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.
- Cardinalidade: digite um número de 1 a 20. A cardinalidade especifica o número máximo de valores que o atributo pode ter.
- Tipo de recurso: selecione o tipo do recurso.
- ID: digite um identificador exclusivo para o atributo.
- Para adicionar um novo valor, clique em Adicionar valor e digite o novo valor que você quer.
- 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.
-
- Para atualizar o nome do atributo, digite o novo nome no campo Nome.
- Para adicionar um novo valor, clique em Adicionar valor e digite o novo valor que você quer.
- Para excluir um valor existente, clique em Excluir no valor que você quer remover.
- 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.