Introducción a API Center
En este ejercicio, aprenderá a:
Cree un servicio de API Center.
Defina propiedades de metadatos.
Agregue API a API Center.
Agregue implementaciones y entornos.
Requisitos previos
Para empezar a administrar API a través de API Center, necesita lo siguiente:
- Suscripción a Azure.
- El proveedor de recursos Microsoft.ApiCenter registrado en su suscripción.
- Como mínimo una asignación de rol de colaborador o permisos equivalentes en la suscripción de Azure.
Nota:
Si aún no lo ha hecho, debe registrar el proveedor de recursos Microsoft.ApiCenter en la suscripción.
- Inicie sesión en Azure Portal.
- Escriba Suscripciones en la barra de búsqueda.
- Seleccione la suscripción en la que desea crear el Centro de API.
- En el menú izquierdo, en Recursos, seleccione Proveedores de recursos.
- Busque Microsoft.ApiCenter en la lista de proveedores de recursos. Si no está registrado, seleccione Registrar.
Paso 1: Creación de un servicio de API Center
Escriba API Centers en la barra de búsqueda.
Seleccione + Create (+ Crear).
En la pestaña Aspectos básicos, escriba o seleccione la siguiente configuración:
a. Seleccione su suscripción a Azure.
b. Seleccione un grupo de recursos existente o haga clic en Nuevo para crear uno nuevo.
c. Escriba un Nombre para el centro de API. Debe ser único en la región donde va a crear el centro de API.
d. En Región, seleccione una de las regiones disponibles para el API Center.
e. Para el plan de precios, seleccione Evaluación gratuita (0 $ durante 90 días).
f. Seleccione Revisar + crear.
h. Una vez completada la validación, seleccione Crear.
Después de la implementación, el centro de API está listo para usarse.
Para ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure e inicie sesión con el comando siguiente.
az login
Nota:
Si aún no lo ha hecho, debe registrar el proveedor de recursos Microsoft.ApiCenter en la suscripción.
Para registrar el proveedor de recursos, ejecute el siguiente comando
az provider register –namespace Microsoft.ApiCenter
Paso 1: Creación de un servicio de API Center
Cree un grupo de recursos ejecutando el siguiente comando, pasando:
- Ejemplo de nombre del grupo de recursos --name. Contoso
- Ejemplo de ubicación --location. Eastus
az group create –-name contoso –-location eastus
Nota:
Los comandos az apic requieren la extensión apic-extension de la CLI de Azure. Si no ha usado comandos az apic, la extensión se instalará dinámicamente cuando ejecute su primer comando az apic, o puede instalar la extensión manualmente. Obtenga más información sobre las extensiones de la CLI de Azure.
Cree un API Center ejecutando el siguiente comando, pasando:
- Ejemplo de un nombre del servicio de API Center -n. contoso-apis
- Ejemplo del grupo de recursos -g. Contoso
- Ejemplo de ubicación --l. Eastus
az apic create -n contoso-apis -g contoso -l eastus
Nota:
De forma predeterminada, el API Center se creará bajo el Plan de tarifa gratuita.
Nota:
Actualmente no se admite la creación de un servicio de API Center en VS Code. Cree uno mediante la CLI de Azure o Azure Portal.
Paso 2: Definir propiedades de metadatos
API Center usa propiedades de metadatos para organizar las API del inventario y habilitar operaciones como el filtrado, la búsqueda, etc.
Nota:
No incluya información confidencial, confidencial ni personal en los nombres o títulos de propiedades de metadatos.
Contoso, al igual que muchas otras organizaciones, desea que todas sus API pasen a través de un aprobador antes de que estén disponibles para su uso y quiere asegurarse de que se realiza una revisión de cumplimiento para todas las API. La organización también tiene API orientadas al público y las creadas exclusivamente para uso interno. Para aplicar esto a escala en todas las API, agregamos tres propiedades de metadatos personalizadas:
- Aprobador de API de tipo Cadena
- Revisión de cumplimiento de tipo Opciones predefinidas
- Contacto con el público de tipo Booleano
En el menú de la izquierda, seleccione Activos > Metadatos > + Nuevos metadatos.
En la pestaña Detalles, escriba información sobre la propiedad.
a. En Título, escriba Aprobador de API
b. En Descripción, escriba Aprobador de API predeterminado
c. Seleccione el tipo Cadena y seleccione Siguiente
En la pestaña Asignaciones, seleccione Requerido para las API. Seleccione Opcional en Implementaciones y entornos. Seleccione Siguiente.
Seleccione Crear
Repita los mismos pasos para la propiedad Contacto con el público, como se muestra en la imagen siguiente. Para el tipo, seleccione Booleano
En la pestaña Asignaciones, seleccione Requerido para las API. Seleccione No aplicable para Implementaciones y Entornos. Seleccione Siguiente.
Seleccione Crear
Repita los mismos pasos para la propiedad Revisión de cumplimiento, como se muestra en la imagen siguiente. Para el tipo, seleccione Opciones predefinidas y agregue 3 opciones, No iniciado, En curso y Completado
En la pestaña Asignaciones, seleccione Requerido para las API. Seleccione No aplicable para Implementaciones y Entornos
Seleccione Siguiente.
Ahora hay disponible un esquema de metadatos JSON para las API para poder verlo, editarlo y descargarlo. Para verlo, seleccione Ver esquema de metadatos y seleccione API en la lista desplegable.
Esto abre un modal a la derecha con detalles de metadatos, que incluyen propiedades integradas de API Center, como LifecycleStage, Name, Description y TermsOfService entre otras. Si se desplaza hasta la parte inferior del archivo, verá los metadatos personalizados que ha agregado en los pasos anteriores, como se muestra a continuación.
Nota:
Puede agregar y editar propiedades en el esquema en cualquier momento y aplicarlas al instante a todas las API de API Center
Cree un nuevo esquema de metadatos ejecutando el comando siguiente para establecer:
- Nombre de metadatos como api-approver
- Esquema con tipo de propiedad como Cadena y título como Aprobador de API
- Asignaciones como requerido para API mientras que opcional para Entorno e Implementación
az apic metadata create -g contoso -n contoso-apis --metadata-name "api-approver" --schema '{"type":"string","title":"API Approver"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
Repita los mismos pasos para:
- Nombre de metadatos como public-facing
- Esquema con tipo de propiedad como Booleano y título como Cara al público
- Asignaciones como requerido para API mientras que opcional para Entorno e Implementación
Al ejecutar el comando siguiente:
az apic metadata create -g contoso -n contoso-apis --metadata-name "public-facing" --schema '{"type":"boolean", "title":"Public Facing"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
Por último, repita los mismos pasos para:
- Nombre de metadatos como compliance-review
- Esquema con tipo de propiedad como Cadena y título como Revisión de cumplimiento
- Asignaciones como requerido para API mientras que opcional para Entorno e Implementación
Al ejecutar el comando siguiente:
az apic metadata create -g contoso -n contoso-apis --metadata-name "compliance-review" --schema '{"type":"string","title":"Compliance Review", "oneOf":[{"const":"Not Started","description":""},{"const":"In Progress","description":""},{"const":"Completed","description":""}]}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
Puede ejecutar el siguiente comando para ver una lista de todos los metadatos definidos en el Centro de API.
az apic metadata list -g <resource-group-name> -n <api-center-name>
Nota:
Puede agregar y editar propiedades en el esquema en cualquier momento y aplicarlas al instante a todas las API de API Center
Nota:
Esta acción no se admite actualmente en VS Code. Cree uno mediante la CLI de Azure o Azure Portal.
Paso 3: Agregar API al inventario
La organización Contoso quiere recomendar conferencias técnicas para sus equipos de ingeniería como parte de su programa interno de obtención de aptitudes. Agregaremos una API de conferencia con oradores, sesiones y temas.
URL de la API de conferencia: https://bigconference.azurewebsites.net/
Para los siguientes pasos, puede copiar la definición de OpenAPI desde el sitio web anterior y guardarla como un archivo JSON en el equipo local. O bien, sustituya otra definición de API al agregar una API al inventario.
En el portal, vaya al centro de API.
En el menú de la izquierda, seleccione Activos > API > + Registrar API.
En la página Registrar API, agregue la siguiente información necesaria para la API. Verá las propiedades personalizadas de metadatos Aprobador de API, *Contacto con el público y Revisión de cumplimiento que definió en los pasos anteriores en la parte inferior de la página.
Para ver la API creada, en el menú de la izquierda, seleccione Activos > API > API de conferencia.
La pestaña Información general ofrece una vista de la configuración de la API. Expanda Detalles para ver y editar información adicional, como la versión de API y las implementaciones (no tenemos implementaciones en este momento).
Normalmente, querrá agregar una definición de API para la versión de API y API Center admite formatos de especificación de texto, incluidos OpenAPI 2, OpenAPI 3 para REST.
Para agregar una definición,
- En el menú de la izquierda, seleccione Activos > API > Seleccione la API (API de conferencia).
- Expanda Detalles y seleccione Versiones.
- Seleccione la versión (v1) y expanda Detalles.
- En detalles, seleccione Definiciones >Agregar definición.
Puede usar la extensión de Azure API Center para Visual Studio Code para registrar una API en la instancia de API.
Paso 1: Instalar la extensión
Paso 2: Abra la paleta de comandos, "Ctrl + Mayús + P" y escriba API Center: Registrar API
Siga los mensajes para proporcionar la siguiente información para la API:
| Registrar API | Paso a paso |
|---|---|
| Seleccionar servicio de API Center | Seleccionar instancia de API Center |
| Título de API | Escriba el nombre de la API (API de conferencia) |
| Tipo de API | REST |
| Título de la versión de API | Escriba un nombre de versión para la API (v1) |
| Ciclo de vida de la versión de API | Seleccione un ciclo de vida en la lista desplegable (Desarrollo) |
| Título de definición de API | Escriba un nombre para la definición (Definición de API de conferencia) |
| Nombre de la especificación de API | Seleccione una especificación en el desplegable (OpenAPI 2) |
| Selección del archivo de definición de API que se va a importar | Examinar y seleccionar el archivo de definición del almacenamiento |
Actualice la pestaña de la extensión de API Center y la API recién creada aparecerá en el recurso o instancia de API Center correspondiente.
Use el siguiente comando para crear una nueva API, pasando:
- Ejemplo del grupo de recursos -g. Contoso
- Ejemplo de un nombre del servicio de API Center -n. contoso-api-center
- Ejemplo de título --title. API de conferencia
- Ejemplo de id. de API --api-id. conference-api
- Ejemplo de tipo --type. REST
az apic api create -g contoso -n contoso-apis --title "Conference API" --api-id conference-api --type REST
Cree una versión de API con el siguiente comando, pasando:
- Ejemplo del grupo de recursos -g. contoso
- Ejemplo de un nombre del servicio de API Center -n. contoso-apis
- Ejemplo de id. de API --api-id. conference-api
- Ejemplo de título --title. v1.2.2
- Ejemplo de id. de versión --version-id. 03-07-2024
- Ejemplo de fase del ciclo de vida --lifecycle-stage. diseño
az apic api version create -g contoso -n contoso-apis --api-id conference-api --title v1.2.2 --version-id 2024-07-03 --lifecycle-stage design
También puede agregar una definición de API para la versión de API y API Center admite formatos de especificación de texto, incluidos OpenAPI 2, OpenAPI 3 para REST.
Para agregar una definición, use el siguiente comando, pasando:
- Ejemplo del grupo de recursos -g. contoso
- Ejemplo de un nombre del servicio de API Center -n. contoso-apis
- Ejemplo de id. de API --api-id. conference-api
- Ejemplo de id. de versión --version-id. 03-07-2024
- Ejemplo de título --title. OpenAPI
- Ejemplo de id. de definición --definition-id. openapi
az apic api definition create -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --title OpenAPI --definition-id openapi
Para importar un archivo de definición de OpenAPI desde una dirección URL, use el comando az apic api definition import-specification para importar. Ejemplo: https://learn.microsoft.com/cli/azure/apic/api/definition?view=azure-cli-latest#az-apic-api-definition-import-specification-examples
az apic api definition import-specification -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --definition-id openapi --format "link" --value 'https://petstore3.swagger.io/api/v3/openapi.json' --specification '{"name":"openapi","version":"3.0.2"}'
Paso 4: Agregar implementaciones y entornos
Entornos
Un entorno (desarrollo, pruebas, almacenamiento provisional o producción) representa una ubicación donde se implementa un entorno de ejecución de API. Los ingenieros de la plataforma de API de Contoso definen dos entornos, prueba y producción, en su instancia de Centro de API para administrar y realizar un seguimiento de diferentes entornos de ejecución de API en su organización.
Para crear un entorno,
En el menú de la izquierda, seleccione Activos > Entornos > + Nuevo entorno.
Agregue la siguiente información.
Seleccione Crear.
Repita los mismos pasos para el Entorno de producción.
Para crear un entorno, ejecute el siguiente comando de la CLI
az apic environment create -g contoso -n contoso-apis --title ContosoTesting --environment-id contosotesting --type testing
Repita lo mismo para el entorno de producción
az apic environment create -g contoso -n contoso-apis-new --title ContosoProduction --environment-id contosoproduction --type production
Nota:
Actualmente no se admite la creación de entornos en VS Code. Use la CLI de Azure o la opción de Azure Portal para este paso.
Implementaciones
Se proporciona una ubicación única (dirección) para que los usuarios interactúen con la API para cada entorno de ejecución de API en un entorno determinado. Esta ubicación se denomina implementación y una sola versión de API podría tener dos implementaciones: una implementación de almacenamiento provisional y una de producción.
Contoso tiene una API, la API de conferencia, que asociamos con los entornos que creamos.
En el portal, vaya al centro de API.
En el menú de la izquierda, seleccione API y, a continuación, seleccione una API, por ejemplo, la API de conferencia.
En la página de la API de conferencia, expanda Detalles > Implementaciones > + Agregar implementación.
Agregue la siguiente información:
a. Seleccione Prueba de Contoso en la lista desplegable del campo Entorno.
b. Para la definición, haga clic en Seleccionar, elija la versión de API v1 en la lista desplegable y seleccione la definición que agregó anteriormente. Haga clic en Seleccionar.
c. Después de agregar correctamente la definición, agregue una dirección URL de tiempo de ejecución base que será específica para la API en el entorno seleccionado.
Para crear una implementación y asociarla con el entorno que creamos en el paso anterior, ejecute el siguiente comando de la CLI
az apic api deployment create -g contoso-corporation -s contoso-api-center --deployment-id "v1-conference-api" --title "Conference OpenAPI 2" --description "Conference Demo API deployment." --api-id conference-api --environment-id "/workspaces/default/environments/contoso-testing" --definition-id "/workspaces/default/apis/conference-api/versions/v1/definitions/conference-openapi-2" --server '{"runtimeUri":["https://conferenceapi.azurewebsites.net/"]}'
Nota:
Actualmente no se admite la creación de implementaciones en VS Code. Use la CLI de Azure o la opción de Azure Portal para este paso.