Usar metadados para governança de API

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

Metadados incorporados

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

As tabelas a seguir listam 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 necessárias.

APIs

Metadados	Description	Valores de exemplo
tipo	Tipo (tipo) de API	DESCANSO, SABONETE, GraphQL
Estágio do ciclo de vida	Estágio do ciclo de vida de desenvolvimento da API	Design, desenvolvimento
licença	Informações de licença para a API	Identificador SPDX, link para o texto da licença
documentação externa	Site para documentação externa para a API	URL apontando para a documentação
Informação de Contacto	Pontos de contacto para a API	Endereço de e-mail, nome, URL
termos do serviço	Termos de serviço para a API	URL apontando para os termos de serviço

Environments

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

Implementações

Metadados	Description	Valores de exemplo
servidor	Informações do servidor da implantação	URL apontando para o servidor de implantação
state	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
Booleano	Verdadeiro ou falso	IsInternal
número	Valor numérico	Ano de Criação
cadeia (de caracteres)	Valor do texto	GitHubRepository
matriz	Lista de valores	Etiquetas
Escolha integrada	Lista integrada de opções	Department
objecto	Objeto complexo composto por vários tipos	APIApprover

Importante

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

Atribuir metadados a entidades

Propriedades de metadados personalizadas podem ser atribuídas a APIs, ambientes ou implantações em seu centro de APIs. Por exemplo, você pode definir e atribuir metadados de departamento a APIs, de modo que, quando uma API for registrada ou uma nova versão da API for adicionada, o departamento responsável pela API seja especificado.

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

Observação

Defina metadados personalizados a qualquer momento e aplique a APIs e outras entidades em seu centro de APIs.
Depois de definir metadados personalizados, você pode alterar sua atribuição a uma entidade, por exemplo, de obrigatório para opcional para APIs.
Você pode alterar valores de metadados, mas não pode excluir ou alterar o tipo de metadados personalizados atualmente definidos em APIs, ambientes e implantações. Cancele a atribuição dos metadados personalizados das entidades primeiro e, em seguida, você pode excluí-los ou alterá-los.