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 e descrições. Nem todas as propriedades são necessárias.
APIs
| Metadados | Description | Valores de exemplo |
|---|---|---|
| variante | 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 |
| license | 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 de Serviço | termos de serviço para a API | URL apontando para os termos de serviço |
Ambientes
| Metadados | Description | Valores de exemplo |
|---|---|---|
| variante | tipo (tipo) de ambiente | produção, encenação, 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 Kubernetes, servidor Apigee |
| inclusão | Informações de integração para o meio 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 | Exemplo de nome |
|---|---|---|
| boolean | verdadeiro ou falso | IsInternal |
| Número | valor numérico | Ano de Criação |
| string | valor do texto | GitHubRepository |
| matriz | Lista de valores | Etiquetas |
| Escolha integrada | lista integrada de opções | Departamento |
| objeto | objeto complexo composto de 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, defina e atribua metadados de departamento a 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 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.
Nota
- 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.
Usar metadados para governança
Use metadados internos e personalizados para organizar suas APIs, ambientes e implantações em seu centro de APIs. Por exemplo:
Imponha padrões de governança em sua organização exigindo que determinados metadados sejam definidos para APIs, ambientes e implantações.
Pesquise e filtre APIs em seu centro de APIs por valores de metadados. Você pode filtrar diretamente na página APIs no portal do Azure ou usar a API REST do Centro de APIs do Azure ou a CLI do Azure para consultar APIs com base em valores de determinados metadados.
