Guardado y configuración del servicio Administración de API mediante Git

Artículo
05/12/2023

SE APLICA A: Desarrollador | Básico | Estándar | Premium

Cada instancia del servicio Administración de API mantiene una base de datos de configuración que contiene información sobre la configuración y los metadatos de la instancia del servicio. Es posible hacer cambios en la instancia del servicio; para ello, modifique un valor en Azure Portal con herramientas de Azure como Azure PowerShell o Azure CLI o realice una llamada de API de REST. Pero esto no es todo, puede administrar la configuración de la instancia del servicio con Git, con lo que se posibilitan escenarios como los siguientes:

Control de versiones de configuración: descargue y almacene versiones diferentes de la configuración del servicio
Cambios masivos en la configuración: realice cambios en varios ajustes de la configuración del servicio en el repositorio local e integre los cambios de nuevo en el servidor con una sola operación
Cadena de herramientas y flujo de trabajo familiares de Git: use las herramientas y los flujos de trabajo de Git con los que ya está familiarizado

El diagrama siguiente muestra de forma global los distintos modos de configurar la instancia del servicio de API Management.

Diagrama que compara formas de configurar API Management para Azure.

Cuando hace cambios en el servicio mediante Azure Portal, las herramientas de Azure como Azure PowerShell, Azure CLI o la API de REST, está administrando la base de datos de configuración del servicio mediante el punto de conexión https://{name}.management.azure-api.net, tal como se muestra en el lado derecho del diagrama. En el lado izquierdo del diagrama se muestra cómo administrar la configuración del servicio mediante Git y el repositorio de Git para el servicio ubicado en https://{name}.scm.azure-api.net.

Los pasos siguientes proporcionan una visión general sobre el proceso de administración de la instancia del servicio de API Management mediante Git.

Acceso a la configuración de Git en el servicio
Guardar la base de datos de configuración del servicio en el repositorio de Git
Clonar el repositorio de Git en el equipo local
Desplegar el repositorio más reciente en el equipo local, y confirmar e insertar los cambios de nuevo en el repositorio
Implementar los cambios desde el repositorio en la base de datos de configuración del servicio

Este artículo describe cómo habilitar y usar Git para administrar la configuración del servicio y sirve como referencia para los archivos y las carpetas del repositorio Git.

Importante

Esta característica está diseñada para trabajar con configuraciones de servicio API Management de pequeñas a medianas, como aquellas con un tamaño exportado inferior a 10 MB o con menos de 10 000 entidades. Los servicios con un gran número de entidades (productos, API, operaciones, esquemas, etc.) pueden experimentar errores inesperados al procesar comandos de Git. Si se producen este tipo de errores, reduzca el tamaño de la configuración del servicio e inténtelo de nuevo. Póngase en contacto con el soporte técnico de Azure si necesita ayuda.

Acceso a la configuración de Git en el servicio

Vaya a la instancia de API Management en Azure Portal.
En el menú de la izquierda, en Implementación e infraestructura, seleccione Repositorio.

Captura de pantalla que muestra cómo acceder a la configuración de Git para API Management.

Guarde la configuración del servicio en el repositorio de Git

Precaución

Los secretos que no se definan como valores con nombre se almacenarán en el repositorio y permanecerán en su historial. Los valores con nombre proporcionan un lugar seguro para administrar los valores de cadena constante, como los secretos, en toda la configuración y las directivas de API, por lo que no tiene que almacenarlos directamente en las instrucciones de directiva. Para más información, consulte Uso de valores con nombre en las directivas de Azure API Management.

Antes de la clonación del repositorio, guarde el estado actual de la configuración del servicio en el repositorio.

En la página Repositorio, seleccione Guardar en el repositorio.
Realice los cambios deseados en la pantalla de confirmación, como el nombre de la rama para guardar la configuración y seleccione Guardar.

Transcurridos unos segundos, la configuración se guarda y se muestra el estado de configuración del repositorio, incluidas la fecha y la hora del último cambio de configuración y la última sincronización entre la configuración del servicio y el repositorio.

Una vez que la configuración se guarda en el repositorio, se puede clonar.

Para obtener información sobre cómo guardar la configuración del servicio mediante la API de REST, consulte Configuración de inquilinos: Guardar.

Consiga credenciales de acceso

Para clonar un repositorio, además de la dirección URL del repositorio, necesita un nombre de usuario y una contraseña.

En la página Repositorio, seleccione Credenciales de acceso cerca de la parte superior de la página.
Anote el nombre de usuario proporcionado en la página Credenciales de acceso.
Para generar una contraseña, primero asegúrese de que el campo Expiración refleja la fecha y la hora de caducidad deseada y luego seleccione Generar.

Importante

Anote esta contraseña. Una vez que salga de esta página, la contraseña no se volverá a mostrar.

Clonar el repositorio en el equipo local

En los ejemplos siguientes se usa la herramienta Git Bash desde Git para Windows, pero puede usar cualquier herramienta de Git con la que esté familiarizado.

Abra su herramienta Git en la carpeta deseada y ejecute el siguiente comando para clonar el repositorio de Git en el equipo local, usando para ello el comando siguiente:

git clone https://{name}.scm.azure-api.net/

Proporcione el nombre de usuario y la contraseña cuando se le solicite.

Si recibe algún error, pruebe a modificar su comando git clone para incluir el nombre de usuario y la contraseña, como se muestra en el ejemplo siguiente.

git clone https://username:password@{name}.scm.azure-api.net/

Si de este modo aparece un error, pruebe a codificar como dirección URL la parte de la contraseña del comando. Una manera rápida de hacer esto es abrir Visual Studio y emitir el siguiente comando en la Ventana Inmediato. Para abrir la Ventana Inmediato, abra cualquier solución o proyecto en Visual Studio (o cree una aplicación de consola vacía) y elija Ventanas, Inmediato en el menú Depurar.

?System.Net.WebUtility.UrlEncode("password from the Azure portal")

Utilice la contraseña codificada junto con su nombre de usuario y ubicación de repositorio para construir el comando git.

git clone https://username:url encoded password@{name}.scm.azure-api.net/

Una vez completada la clonación, cambie el directorio a su repositorio ejecutando un comando similar al siguiente.

cd {name}.scm.azure-api.net/

Si ha guardado la configuración en una rama distinta de la rama predeterminada (master), consulte la rama:

git checkout <branch_name>

Una vez que se clone el repositorio, podrá ver y trabajar con él en el sistema de archivos local. Para más información, consulte Referencia de estructura de archivo y carpeta del repositorio local de Git.

Actualice su repositorio local con la configuración de instancia de servicio más reciente

Si realiza cambios en la instancia del servicio de API Management en Azure Portal o mediante otras herramientas Azure, debe guardar estos cambios en el repositorio para poder actualizar el repositorio local con los cambios más recientes.

Para guardar los cambios mediante el Azure Portal, seleccione Guardar en el repositorio en la pestaña Repositorio de la instancia de API Management.

Entonces, para actualizar su repositorio local:

Asegúrese de que se encuentra en la carpeta del repositorio local. Si acaba de completar el comando git clone, debe cambiar el directorio a su repositorio ejecutando un comando similar al siguiente.
```
cd {name}.scm.azure-api.net/
```
En la carpeta del repositorio local, emita el siguiente comando.
```
git pull
```

Inserte los cambios desde su repositorio local al repositorio del servidor

Para insertar los cambios desde el repositorio local al repositorio del servidor, debe confirmar los cambios y, a continuación, insertarlos en el repositorio del servidor. Para confirmar los cambios, abra la herramienta de comandos de Git, cambie al directorio del repositorio local y emita los siguientes comandos.

git add --all
git commit -m "Description of your changes"

Para insertar todas las confirmaciones en el servidor, ejecute el siguiente comando.

git push

Implemente los cambios de la configuración del servicio en la instancia del servicio de API Management

Una vez confirmados los cambios locales e insertados en el repositorio del servidor, puede implementarlos en la instancia del servicio Administración de API.

Vaya a la instancia de API Management en Azure Portal.
En el menú de la izquierda, en Implementación e infraestructura, seleccione Repositorio>Implementación a API Management.
En la página Implementar configuración del repositorio, escriba el nombre de la rama que contiene los cambios de configuración deseados y, opcionalmente, seleccione Quitar suscripciones de productos eliminados. Seleccione Guardar.

Para obtener información sobre cómo realizar esta operación mediante la API de REST, consulte Configuración de inquilinos: implementación.

Referencia de estructura de archivo y carpeta del repositorio local de Git

Los archivos y carpetas del repositorio local de Git contienen la información de configuración acerca de la instancia de servicio.

Elemento	Descripción
carpeta raíz de la administración de API	Contiene la configuración de nivel superior para la instancia de servicio
carpeta apiReleases	Contiene la configuración para las versiones de API de la instancia de servicio
carpeta de API	Contiene la configuración para las API de la instancia de servicio
apiVersionSets folder	Contiene la configuración para el conjunto de versión de las API de la instancia de servicio
carpeta back-ends	Contiene la configuración para las recursos back-end de la instancia de servicio
carpeta de grupos	Contiene la configuración para los grupos de la instancia de servicio
carpeta de directivas	Contiene las directivas de la instancia de servicio
carpeta portalStyles	Contiene la configuración para las personalizaciones del portal para desarrolladores de la instancia de servicio
carpeta portalTemplates	Contiene la configuración para las plantillas del portal para desarrolladores de la instancia de servicio
carpeta de productos	Contiene la configuración para los productos de la instancia de servicio
carpeta de plantillas	Contiene la configuración para las plantillas de correo electrónico de la instancia de servicio

Cada carpeta puede contener uno o varios archivos y, en algunos casos, una o varias carpetas; por ejemplo, una carpeta para cada API, producto o grupo. Los archivos dentro de cada carpeta son específicos del tipo de entidad descrito por el nombre de la carpeta.

Tipo de archivo	Propósito
json	Información de configuración acerca de la entidad correspondiente
html	Descripción de la entidad, a menudo mostrada en el portal para desarrolladores
Xml	Policy statements
css	Hojas de estilo para la personalización del portal para desarrolladores

Estos archivos se pueden crear, eliminar, editar y administrar en el sistema de archivos local, y los cambios se pueden implementar de nuevo en la instancia de servicio de API Management.

Nota

Las siguientes entidades no están en el repositorio de Git y no se pueden configurar mediante Git.

Usuarios
Suscripciones
Valores con nombre
Entidades del portal de desarrolladores distintas de los estilos y plantillas
Fragmentos de directiva

carpeta raíz de la administración de API

La carpeta raíz api-management contiene un archivo configuration.json con información de nivel superior sobre la instancia de servicio en el formato siguiente.

{
  "settings": {
    "RegistrationEnabled": "True",
    "UserRegistrationTerms": null,
    "UserRegistrationTermsEnabled": "False",
    "UserRegistrationTermsConsentRequired": "False",
    "DelegationEnabled": "False",
    "DelegationUrl": "",
    "DelegatedSubscriptionEnabled": "False",
    "DelegationValidationKey": "",
    "RequireUserSigninEnabled": "false"
  },
  "$ref-policy": "api-management/policies/global.xml"
}

Los primeros cuatro valores (RegistrationEnabled, UserRegistrationTerms, UserRegistrationTermsEnabled y UserRegistrationTermsConsentRequired) se asignan a la siguiente configuración en la pestaña Identidades de la sección Portal para desarrolladores.

Configuración de identidad	Se asigna a
RegistrationEnabled	Presencia del proveedor de identidades Nombre de usuario y contraseña
UserRegistrationTerms	Condiciones de uso del registro de usuario
UserRegistrationTermsEnabled	Mostrar condiciones de uso en la página de registro
UserRegistrationTermsConsentRequired	Requerir consentimiento
RequireUserSigninEnabled	Redirigir a los usuarios anónimos a la página de inicio de sesión

La cuatro valores siguientes (DelegationEnabled, DelegationUrl, DelegatedSubscriptionEnabled y DelegationValidationKey) se asignan a la siguiente configuración en la pestaña Delegación de la sección Portal para desarrolladores.

Configuración de delegación	Se asigna a
DelegationEnabled	Casilla Delegar inicio de sesión y registro
DelegationUrl	Dirección URL del punto de conexión de delegación
DelegatedSubscriptionEnabled	Delegar suscripción de producto
DelegationValidationKey	Delegar clave de validación

El valor final, $ref-policy, se asigna al archivo de instrucciones de directiva global para la instancia de servicio.

carpeta apiReleases

La carpeta apiReleases contiene una carpeta para cada versión de API implementada en una API de producción y contiene los siguientes elementos.

apiReleases\<api release Id>\configuration.json: configuración de la versión, que contiene información sobre las fechas de lanzamiento. Se trata de la misma información que se devolvería si se llamase a la operación Obtener un lanzamiento específico.

carpeta de API

La carpeta apis contiene una carpeta para cada API de la instancia de servicio, que contiene los elementos siguientes.

apis\<api name>\configuration.json: configuración de la API y contiene información acerca de la dirección URL del servicio back-end y las operaciones. Se trata de la misma información que se devolvería si se llamase a la operación Obtener una API específica.
apis\<api name>\api.description.html: descripción de la API, correspondiente a la description propiedad de la entidad de API en la API REST.
apis\<api name>\operations\: esta carpeta contiene archivos <operation name>.description.html que se asignan a las operaciones de la API. Cada archivo contiene la descripción de una única operación en la API, que se asigna a la propiedad description de la entidad de operación en la API de REST.

apiVersionSets folder

La carpeta apiVersionSets contiene una carpeta para cada conjunto de versiones de API creado para una API y contiene los siguientes elementos.

apiVersionSets\<api version set Id>\configuration.json: configuración del conjunto de versiones. Se trata de la misma información que se devolvería si se llamase a la operación Obtener un conjunto de versión específico.

carpeta de grupos

La carpeta groups contiene una carpeta para cada grupo definido en la instancia de servicio.

groups\<group name>\configuration.json: configuración del grupo. Se trata de la misma información que se devolvería si se llamase a la operación Obtener un grupo específico .
groups\<group name>\description.html: descripción del grupo y corresponde a la propiedad description de la entidad de servicio.

carpeta de directivas

La carpeta policies contiene las instrucciones de directiva para la instancia de servicio.

policies\global.xml : contiene las directivas definidas en el ámbito global para la instancia de servicio.
policies\apis\<api name>\: si tiene directivas definidas en el ámbito de la API, se encuentran en esta carpeta.
Carpeta policies\apis\<api name>\<operation name>\: si tiene directivas definidas en el ámbito de la operación, se encuentran en esta carpeta en archivos <operation name>.xml que se asignan a las instrucciones de directiva para cada operación.
policies\products\: si tiene directivas definidas en el ámbito del producto, se encuentran esta carpeta, que contiene archivos <product name>.xml que se asignan a las instrucciones de directiva para cada producto.

carpeta portalStyles

La carpeta portalStyles contiene la configuración y las hojas de estilo para personalizar el portal de desarrolladores en desuso de la instancia de servicio.

portalStyles\configuration.json: contiene los nombres de las hojas de estilos usadas por el portal de desarrolladores
portalStyles\<style name>.css: cada archivo <style name>.css contiene estilos para el portal para desarrolladores (Preview.css y Production.css de forma predeterminada).

carpeta portalTemplates

La carpeta portalTemplates contiene plantillas para personalizar el portal para desarrolladores en desuso de la instancia de servicio.

portalTemplates\<template name>\configuration.json: configuración de la plantilla.
portalTemplates\<template name>\<page name>.html: páginas HTML originales y modificadas de la plantilla.

carpeta de productos

La carpeta products contiene una carpeta para cada producto que se define en la instancia de servicio.

products\<product name>\configuration.json: configuración del producto. Se trata de la misma información que se devolvería si se llamase a la operación Obtener un producto específico .
products\<product name>\product.description.html: descripción del producto y corresponde a la propiedad description de la entidad de producto de la API de REST.

plantillas

La carpeta templates contiene la configuración para las plantillas de correo electrónico de la instancia de servicio.

<template name>\configuration.json: configuración para la plantilla de correo electrónico.
<template name>\body.html: cuerpo de la plantilla de correo electrónico.

Pasos siguientes

Para obtener información sobre otras formas de administrar la instancia de servicio, consulte:

Compartir vía