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 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 em 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 e descrições. Nem todas as propriedades são obrigatórias.
APIs
| Metadados | Descrição | Valores de exemplo |
|---|---|---|
| kind | tipo de API | REST, SOAP, GraphQL |
| fase do ciclo de vida | fase do ciclo de vida de desenvolvimento da API | design, desenvolvimento |
| license | informações de licença da API | identificador SPDX, link para texto da licença |
| documentação externa | site para documentação externa da API | URL apontando para a documentação |
| informações de contato | pontos de contato para a 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 |
Ambientes
| Metadados | Descrição | Valores de exemplo |
|---|---|---|
| kind | tipo de ambiente | produção, preparo, desenvolvimento |
| servidor | informações do servidor do ambiente | tipo e URL apontando para o servidor do ambiente |
| tipo de servidor | tipo do servidor do ambiente | servidor de Gerenciamento de API, servidor do Kubernetes, servidor do Apigee |
| integração | informações de integração do ambiente | instruções e URL apontando para o portal do desenvolvedor do ambiente |
Implantações
| Metadados | Descrição | Valores de exemplo |
|---|---|---|
| servidor | informações do servidor de 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 | Descrição | Nome de exemplo |
|---|---|---|
| boolean | true ou false | IsInternal |
| número | numeric value | YearOfCreation |
| string | valor de texto | GitHubRepository |
| matriz | lista de valores | Marcas |
| escolha interna | lista interna de opções | Departamento |
| objeto | objeto complexo composto de 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, defina e atribua metadados Department às 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 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.
Usar metadados para governança
Use metadados internos e personalizados para organizar suas APIs, ambientes e implantações no centro de API. 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 no centro de API por valores de metadados. Você pode filtrar diretamente na página de APIs no portal do Azure ou usar a API REST do Centro de API do Azure ou a CLI do Azure para consultar APIs com base em valores de determinados metadados.
