Usar metadados para governança de API

Este artigo fornece informações em segundo plano sobre metadados e como usá-los na governança de API no Centro de API do Azure. Você define metadados para organizar e filtrar APIs e outras entidades no centro de API. Os metadados podem ser internos ou personalizados e você pode desenvolver um esquema de metadados para impor consistência nas suas APIs, ambientes e implantações.

Metadados internos

Ao criar ou atualizar APIs, ambientes e implantações no centro de API, você define determinadas propriedades de metadados internas, como o tipo de API (REST, WSDL e assim por diante).

As tabelas a seguir listam os metadados internos fornecidos para entidades do Centro de API do Azure. Para obter detalhes, consulte a Referência da API REST do Centro de API. As tabelas não incluem propriedades padrão do Azure, como identificadores de recursos, títulos de exibição ou descrições. Nem todas as propriedades são obrigatórias.

APIs

Metadados	Description	Valores de exemplo
variante	Tipo (tipo) de API	REST, SOAP, GraphQL
fase do ciclo de vida	Estágio do ciclo de vida de desenvolvimento da API	Design, desenvolvimento
licença	Informações de licença da API	identificador SPDX, link para texto da licença
documentação externa	Site da documentação externa da API	URL apontando para a documentação
informações de contato	Pontos de contato da API	Endereço de email, nome, URL
termos de serviço	Termos de serviço da API	URL apontando para os termos de serviço

Environments

Metadados	Description	Valores de exemplo
variante	Tipo (tipo) de ambiente	Produção, preparo, desenvolvimento
servidor	Informações do servidor do ambiente	Tipo e URL apontando para o servidor de ambiente
tipo de servidor	Tipo de servidor de ambiente	servidor de Gerenciamento de API, servidor do Kubernetes, servidor do Apigee
integração	Informações de integração para o ambiente	Instruções e URL apontando para o portal do desenvolvedor do ambiente

Implantações

Metadados	Description	Valores de exemplo
servidor	Informações do servidor da implantação	URL apontando para o servidor de implantação
estado	Estado da implantação	Ativo, inativo

Metadados personalizados

Defina metadados personalizados usando o portal do Azure, a API REST do Centro de API do Azure ou a CLI do Azure para ajudar a organizar e filtrar APIs, ambientes e implantações em seu centro de API. O Centro de API do Azure dá suporte a metadados personalizados dos seguintes tipos.

Tipo	Description	Nome de exemplo
boolean	Verdadeiro ou falso	IsInternal
número	Valor numérico	YearOfCreation
cadeia	Valor do texto	GitHubRepository
matriz	Lista de valores	Tags
escolha interna	Lista interna de opções	Department
objeto	Objeto complexo composto por vários tipos	APIApprover

Importante

Não inclua informações confidenciais ou pessoais nos títulos (nomes) dos metadados que você definir. Esses títulos ficam visíveis nos logs de monitoramento utilizados pela Microsoft para melhorar a funcionalidade do serviço. Entretanto, outros detalhes e valores de metadados são seus dados de cliente protegidos.

Atribuir metadados a entidades

As propriedades de metadados personalizados podem ser atribuídas a APIs, ambientes ou implantações no centro de API. Por exemplo, você pode definir e atribuir metadados do Departamento nas APIs, de modo que, quando uma API é registrada ou uma nova versão da API é adicionada, o departamento responsável pela API é especificado.

Se atribuídos a uma entidade, os metadados serão opcionais ou obrigatórios. Por exemplo você pode exigir que os metadados Department sejam definidos apenas para APIs, mas permitir que YearOfCreation seja metadados opcionais para ambientes.

Observação

Defina metadados personalizados a qualquer momento e aplique-os a APIs e outras entidades no centro de API.
Depois de definir metadados personalizados, você pode alterar sua atribuição para uma entidade, por exemplo, de obrigatória para opcional para APIs.
Você pode alterar valores de metadados, mas não pode excluir ou alterar o tipo de metadados personalizados que está atualmente definido em APIs, ambientes e implantações. Cancele a atribuição dos metadados personalizados das entidades primeiro e, em seguida, exclua-os ou altere-os.