Uso de metadatos para la gobernanza de API
En este artículo se proporciona información general sobre los metadatos y cómo usarlo para la gobernanza de API en el Centro de API de Azure. Defina y establezca metadatos para organizar y filtrar las API y otras entidades del centro de API. Los metadatos se pueden compilar o personalizar, y puede desarrollar un esquema de metadatos para aplicar la coherencia en las API, los entornos y las implementaciones.
Metadatos integrados
Al crear o actualizar API, entornos e implementaciones en el centro de API, se establecen determinadas propiedades de metadatos integradas, como el tipo de API (REST, WSDL, etc.).
En las tablas siguientes se enumeran los metadatos integrados proporcionados para las entidades del Centro de API de Azure. Para más información, consulte la referencia de la API de REST del Centro de API. Las tablas no incluyen propiedades estándar de Azure, como identificadores de recursos, títulos para mostrar y descripciones. No todas las propiedades son necesarias.
API existentes
| Metadatos | Descripción | Valores de ejemplo |
|---|---|---|
| kind | clase (tipo) de API | REST, SOAP, GraphQL |
| fase del ciclo de vida | fase del ciclo de vida de desarrollo de la API | diseño, desarrollo |
| license | información de licencia para la API | identificador SPDX, vínculo al texto de licencia |
| documentación externa | sitio para documentación externa para la API | dirección URL que apunta a la documentación |
| información de contacto | puntos de contacto para la API | dirección de correo electrónico, nombre, dirección URL |
| términos de servicio | términos de servicio para la API | dirección URL que apunta a términos de servicio |
Entornos
| Metadatos | Descripción | Valores de ejemplo |
|---|---|---|
| kind | clase (tipo) del entorno | producción, ensayo, desarrollo |
| server | información del servidor del entorno | tipo y dirección URL que apuntan al servidor de entorno |
| tipo de servidor | tipo de servidor de entorno | servidor de API Management, servidor de Kubernetes, servidor de Apigee |
| incorporación | información de incorporación para el entorno | instrucciones y direcciones URL que apuntan al portal para desarrolladores del entorno |
Implementaciones
| Metadatos | Descripción | Valores de ejemplo |
|---|---|---|
| server | información del servidor de la implementación | dirección URL que apunta al servidor de implementación |
| estado | estado de la implementación | activo, inactivo |
Metadatos personalizados
Defina metadatos personalizados mediante Azure Portal, la API de REST del Centro de API de Azure o la CLI de Azure para ayudar a organizar y filtrar las API, los entornos y las implementaciones en el centro de API. El Centro de API de Azure admite metadatos personalizados de los siguientes tipos.
| Tipo | Descripción | Nombre del ejemplo |
|---|---|---|
| boolean | true o false | IsInternal |
| number | Valor numérico | YearOfCreation |
| string | valor de texto | GitHubRepository |
| array | Lista de valores | Etiquetas |
| elección integrada | lista integrada de opciones | Departamento |
| objeto | objeto complejo compuesto por varios tipos | APIApprover |
Importante
No incluya ninguna información confidencial, confidencial o personal en los títulos (nombres) de metadatos que defina. Estos títulos son visibles en los registros de supervisión que Microsoft usa para mejorar la funcionalidad del servicio. Sin embargo, otros detalles y valores de metadatos son los datos protegidos del cliente.
Asignación de metadatos a entidades
Las propiedades de metadatos personalizadas se pueden asignar a API, entornos o implementaciones en el centro de API. Por ejemplo, defina y asigne metadatos de Departamento a las API, de modo que cuando se registre una API o se agregue una nueva versión de API, se especifica el departamento responsable de la API.
Si se asigna a una entidad, los metadatos son opcionales o obligatorios. Por ejemplo, puede requerir que los metadatos del Departamento solo se establezcan para las API, pero permitir que YearOfCreation sea metadatos opcionales para entornos.
Nota:
- Defina metadatos personalizados en cualquier momento y aplíquelos a las API y a otras entidades del centro de API.
- Después de definir metadatos personalizados, puede cambiar su asignación a una entidad, por ejemplo, de obligatoria a opcional para las API.
- Puede cambiar los valores de metadatos, pero no puede eliminar ni cambiar el tipo de metadatos personalizados que está establecido actualmente en las API, los entornos y las implementaciones. Desasigne primero los metadatos personalizados de las entidades y, a continuación, puede eliminarlos o cambiarlos.
Uso de metadatos para la gobernanza
Use metadatos integrados y personalizados para organizar las API, los entornos y las implementaciones en el centro de API. Por ejemplo:
Aplique los estándares de gobernanza de su organización al exigir que determinados metadatos se establezcan para las API, los entornos y las implementaciones.
Busque y filtre las API en el centro de API por valores de metadatos. Puede filtrar directamente en la página de API de Azure Portal o usar la API de REST del Centro de API de Azure o la CLI de Azure para consultar las API en función de los valores de determinados metadatos.
