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

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.

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.

1. Acceso a la configuración de Git en el servicio
2. Guardar la base de datos de configuración del servicio en el repositorio de Git
3. Clonar el repositorio de Git en el equipo local
4. Desplegar el repositorio más reciente en el equipo local, y confirmar e insertar los cambios de nuevo en el repositorio
5. 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.

1. Vaya a la instancia de API Management en Azure Portal.

2. En el menú de la izquierda, en Implementación e infraestructura, seleccione Repositorio.

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

1. En la página Repositorio, seleccione Guardar en el repositorio.

2. 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.

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

1. En la página Repositorio, seleccione Credenciales de acceso cerca de la parte superior de la página.

2. Anote el nombre de usuario proporcionado en la página Credenciales de acceso.

3. 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.

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, como se muestra en el ejemplo siguiente. Proporcione la contraseña cuando se le solicite.

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

Si esto proporciona un error, pruebe la codificación de la dirección URL de la contraseña y pásela en el 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.

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:

1. 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/
   

2. En la carpeta del repositorio local, emita el siguiente comando.

   git pull
   

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

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

1. Vaya a la instancia de API Management en Azure Portal.

2. En el menú de la izquierda, en Implementación e infraestructura, seleccione Repositorio>Implementación a API Management.

3. 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.

Los archivos y carpetas del repositorio local de Git contienen la información de configuración acerca 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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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).

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.

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.

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.

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

• Referencia de cmdlets de Azure PowerShell
• Referencia de la CLI de Azure
• API Management REST API (API de REST de Administración de API)
• Lanzamientos de Azure SDK