Inscrire des API dans votre Centre API à l’aide de GitHub Actions

Article
07/26/2024

Cet article explique comment configurer un workflow GitHub Actions de base pour inscrire une API dans le Centre API de votre organisation lorsqu’un fichier de spécification d’API est ajouté à un dépôt GitHub.

L’utilisation d’un workflow GitHub Actions pour inscrire des API dans votre Centre API fournit un processus CI/CD cohérent et reproductible pour chaque API nouvelle ou mise à jour. Le workflow peut être étendu pour inclure des étapes telles que l’ajout de métadonnées à l’inscription de l’API.

Le diagramme suivant montre comment l’inscription d’API dans votre Centre API peut être automatisée à l’aide d’un workflow GitHub Actions.

Configurez un workflow GitHub Actions dans votre dépôt qui se déclenche lorsqu’une demande de tirage (pull request) qui ajoute un fichier de définition d’API est fusionnée.
Créez une branche à partir de la branche principale dans votre dépôt GitHub.
Ajoutez un fichier de définition d’API, commitez les modifications et envoyez-les vers la nouvelle branche.
Créez une demande de tirage pour fusionner la nouvelle branche dans la branche principale.
Fusionner la demande de tirage.
La fusion déclenche un workflow GitHub Actions qui inscrit l’API dans votre Centre API.

Prérequis

Un Centre d’API dans votre abonnement Azure. Si vous n’en avez pas encore créé, consultez Démarrage rapide : Créer votre centre d’API.
Autorisations pour créer un principal de service dans le locataire Microsoft Entra ID
Un compte GitHub et un dépôt GitHub dans lequel vous pouvez configurer des secrets et des workflows GitHub Actions
Pour Azure CLI :
- Utilisez l’environnement Bash dans Azure Cloud Shell. Pour plus d’informations, consultez Démarrage rapide pour Bash dans Azure Cloud Shell.
- Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker. Pour plus d’informations, consultez Guide pratique pour exécuter Azure CLI dans un conteneur Docker.
  - Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login. Pour finir le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour connaître les autres options de connexion, consultez Se connecter avec Azure CLI.
  - Lorsque vous y êtes invité, installez l’extension Azure CLI lors de la première utilisation. Pour plus d’informations sur les extensions, consultez Utiliser des extensions avec Azure CLI.
  - Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.
Remarque

Les commandes az apic nécessitent l’extension Azure CLI apic-extension. Si vous n’avez pas utilisé de commandes az apic, l’extension peut être installée dynamiquement lorsque vous exécutez votre première commande az apic, ou vous pouvez l’installer manuellement. Apprenez-en davantage sur les extensions Azure CLI.

Pour connaître les dernières modifications et mises à jour relatives à apic-extension, consultez les notes de publication.

Remarque

Les exemples de commandes Azure CLI de cet article peuvent s’exécuter dans PowerShell ou dans un interpréteur de commandes bash. Si c’est nécessaire en raison d’une syntaxe de variables différente, des exemples distincts de commandes sont fournis pour les deux interpréteurs de commandes.

Configurer un workflow GitHub Actions

Dans cette section, vous allez configurer le workflow GitHub Actions pour ce scénario :

Créer un principal de service à utiliser pour les informations d’identification Azure dans le workflow.
Ajouter les informations d’identification en tant que secret dans votre dépôt GitHub.
Configurer un workflow GitHub Actions qui se déclenche lorsqu’une demande de tirage qui ajoute un fichier de définition d’API est fusionnée. Le fichier YAML de workflow inclut une étape qui utilise Azure CLI pour inscrire l’API dans votre Centre API à partir du fichier de définition.

Configurer un secret de principal de service

Lors des étapes suivantes, vous allez créer un principal de service Microsoft Entra ID qui sera utilisé pour ajouter des informations d’identification au workflow afin de s’authentifier auprès d’Azure.

Remarque

La configuration d’un principal de service est illustrée à des fins de démonstration. La méthode recommandée pour s’authentifier auprès d’Azure pour GitHub Actions consiste à utiliser OpenID Connect, une méthode d’authentification qui utilise des jetons de courte durée. La configuration d’OpenID Connect avec GitHub Actions est plus complexe, mais offre une sécurité renforcée. En savoir plus

Créez un principal du service à l’aide de la commande az ad sp create-for-rbac. L’exemple suivant utilise d’abord la commande az apic show pour récupérer l’ID de ressource du Centre API. Le principal de service est alors créé avec le rôle Azure API Center Service Contributor pour le centre API.

Bash
PowerShell

#! /bin/bash
apiCenter=<api-center-name>
resourceGroup=<resource-group-name>
spName=<service-principal-name>

apicResourceId=$(az apic show --name $apiCenter --resource-group $resourceGroup --query "id" --output tsv)

az ad sp create-for-rbac --name $spName --role "Azure API Center Service Contributor" --scopes $apicResourceId --json-auth

# PowerShell syntax
$apiCenter = "<api-center-name>"
$resourceGroup = "<resource-group-name>"
$spName = "<service-principal-name>"

$apicResourceId = $(az apic show --name $apiCenter --resource-group $resourceGroup --query "id" --output tsv)

az ad sp create-for-rbac --name $spName --role "Azure API Center Service Contributor" --scopes $apicResourceId --json-auth

Copiez la sortie JSON, qui doit ressembler à ce qui suit :

{
  "clientId": "<GUID>",
  "clientSecret": "<GUID>",
  "subscriptionId": "<GUID>",
  "tenantId": "<GUID>",
  "activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
  "resourceManagerEndpointUrl": "https://management.azure.com/",
  [...other endpoints...]
}

Ajouter le principal de service en tant que secret GitHub

Dans GitHub, accédez à votre référentiel. Cliquez sur Paramètres.
Sous Sécurité, sélectionnez Secrets et variables>Actions.
Sélectionnez New repository secret (Nouveau secret de dépôt).
Collez l’intégralité de la sortie JSON de la commande Azure CLI dans le champ de valeur du secret. Nommez le secret AZURE_CREDENTIALS. Sélectionnez Ajouter un secret.

Le secret est répertorié sous Secrets du dépôt.

Quand vous configurerez le fichier de workflow GitHub ultérieurement, vous utiliserez le secret pour l’entrée creds de l’action Azure/login. Par exemple :

- uses: azure/login@v1
  with:
    creds: ${{ secrets.AZURE_CREDENTIALS }}

Ajouter le fichier de workflow à votre référentiel GitHub

Un workflow GitHub Actions est représenté par un fichier de définition YAML (.yml). Cette définition contient les étapes et les paramètres qui composent le workflow. En savoir plus

Voici un fichier de workflow de base pour cet exemple, que vous pouvez utiliser ou modifier.

Dans cet exemple :

Le workflow est déclenché lorsqu’une demande de tirage qui ajoute une définition JSON dans le chemin d’accès APIs est fermée sur la branche principale.
L’emplacement de la définition est extrait de la demande de tirage à l’aide d’un script GitHub, qui est authentifié avec le jeton GitHub par défaut.
Les informations d’identification Azure enregistrées dans votre dépôt sont utilisées pour se connecter à Azure.
La commande az apic register inscrit l’API dans le Centre API spécifié dans les variables d’environnement.

Pour configurer le fichier de workflow :

Copiez et enregistrez le fichier sous un nom tel que register-api.yml.
Mettez à jour les valeurs des variables d’environnement pour qu’elles correspondent à votre Centre API dans Azure.
Confirmez ou mettez à jour le nom du dossier du dépôt (APIs) dans lequel vous allez ajouter le fichier de définition d’API.
Ajoutez ce fichier de workflow dans le chemin d’accès /.github/workflows/ de votre dépôt GitHub.

Conseil

À l’aide de l’extension Visual Studio Code pour le Centre API Azure, vous pouvez générer un fichier de workflow de démarrage en exécutant une commande d’extension. Dans la palette de commandes, sélectionnez Centre API Azure : Inscrire des API. Sélectionnez CI/CD>GitHub. Vous pouvez ensuite modifier le fichier pour votre scénario.

name: Register API Definition to Azure API Center
on:
  pull_request:
    types: [closed]
    branches:
      - main
    paths:
      - "APIs/**/*.json"
permissions:
  contents: read
  pull-requests: read
env:
  # set this to your Azure API Center resource group name
  RESOURCE_GROUP: <YOUR_RESOURCE_GROUP>
  # set this to your Azure API Center service name
  SERVICE_NAME: <YOUR_API_CENTER>
jobs:
  register:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v2
    
      - name: Get specification file path in the PR
        id: get-file-location
        uses: actions/github-script@v5
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const pull_number = context.payload.pull_request.number;
            const owner = context.repo.owner;
            const repo = context.repo.repo;
            const files = await github.rest.pulls.listFiles({
              owner,
              repo,
              pull_number
            });
            if (files.data.length === 1) {
              const filename = files.data[0].filename;
              core.exportVariable('API_FILE_LOCATION', hfilename);
              console.log(`API_FILE_LOCATION: ${{ env.API_FILE_LOCATION }}`);
            }
            else {
              console.log('The PR does not add exactly one specification file.');
            }
      - name: Azure login
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}
          
      - name: Register to API Center
        uses: azure/CLI@v2
        with:
          azcliversion: latest
          inlineScript: |
            az apic api register -g ${{ env.RESOURCE_GROUP }} -n ${{ env.SERVICE_NAME }} --api-location ${{ env.API_FILE_LOCATION }}

Ajouter un fichier de définition d’API au dépôt

Testez le workflow en ajoutant un fichier de définition d’API au dépôt. Suivez ces étapes générales, qui sont typiques d’un workflow de développement. Pour plus d’informations sur l’utilisation des branches GitHub, consultez la documentation GitHub.

Créez une branche de travail à partir de la branche principale dans votre dépôt.
Ajoutez le fichier de définition d’API au dépôt dans le chemin d’accès APIs. Par exemple : APIs/catfacts-api/07-15-2024.json.
Commitez les modifications et envoyez-les vers la branche de travail.
Créez une demande de tirage pour fusionner la branche de travail dans la branche principale.
Après révision, fusionnez la demande de tirage. La fusion déclenche le workflow GitHub Actions qui inscrit l’API dans votre Centre API.

Vérifier l’inscription de l’API

Vérifiez que l’API est inscrite dans votre Centre API.

Dans le Portail Microsoft Azure, accédez à votre centre API.
Dans le menu de gauche, sous Ressources, sélectionnezAPI.
Vérifiez que l’API nouvellement inscrite apparaît dans la liste des API.

Capture d’écran de l’API inscrite dans le Centre API après le workflow.

Ajouter une nouvelle version d’API

Pour ajouter une nouvelle version à une API existante dans votre Centre API, suivez les étapes précédentes, avec une légère modification :

Accédez à la même branche de travail dans votre dépôt, ou créez une nouvelle branche de travail.
Ajoutez un nouveau fichier de définition d’API au dépôt dans le chemin d’accès APIs, dans le dossier d’une API existante. Par exemple, si vous avez précédemment ajouté une définition d’API Cat Facts, ajoutez une nouvelle version telle que APIs/catfacts-api/07-22-2024.json.
Commitez les modifications et envoyez-les vers la branche de travail.
Créez une demande de tirage pour fusionner la branche de travail dans la branche principale.
Après révision, fusionnez la demande de tirage. La fusion déclenche le workflow GitHub Actions qui inscrit la nouvelle version de l’API dans votre Centre API.
Dans le portail Azure, accédez à votre Centre API et vérifiez que la nouvelle version est inscrite.

Étendre le scénario

Vous pouvez étendre le workflow GitHub Actions de façon à inclure d’autres étapes, telles que l’ajout de métadonnées pour l’inscription d’API. Par exemple :

À l’aide du schéma de métadonnées dans votre Centre API, créez un fichier JSON de métadonnées pour appliquer des valeurs de métadonnées à votre inscription d’API.

Par exemple, si le schéma de métadonnées inclut des propriétés telles que approver, team et cost center, un fichier JSON de métadonnées peut ressembler à ceci :
```
{
  "approver": "diego@contoso.com",
  "team": "Store API dev team",
  "costCenter": "12345"  
}
```
Chargez un fichier JSON de métadonnées dans le dossier pour chaque API du dépôt.
Ajoutez une étape de workflow pour appliquer les métadonnées à l’inscription d’API à l’aide de la commande az apic api update. Dans l’exemple suivant, l’ID d’API et le fichier de métadonnées sont transmis dans des variables d’environnement, qui seraient définies ailleurs dans le fichier de workflow.
```
[...]
- name: Apply metadata to API in API Center
    uses: azure/CLI@v2
    with:
      azcliversion: latest
      inlineScript: |
        az apic api update -g ${{ env.RESOURCE_GROUP }} -n ${{ env.SERVICE_NAME }} --api-id {{ env.API_ID }} --custom-properties {{ env.METADATA_FILE }}
```

Partager via

Inscrire des API dans votre Centre API à l’aide de GitHub Actions

Prérequis

Configurer un workflow GitHub Actions

Configurer un secret de principal de service

Ajouter le principal de service en tant que secret GitHub

Ajouter le fichier de workflow à votre référentiel GitHub

Ajouter un fichier de définition d’API au dépôt

Vérifier l’inscription de l’API

Ajouter une nouvelle version d’API

Étendre le scénario

Commentaires

Ressources supplémentaires

Partager via

Inscrire des API dans votre Centre API à l’aide de GitHub Actions

Prérequis

Configurer un workflow GitHub Actions

Configurer un secret de principal de service

Ajouter le principal de service en tant que secret GitHub

Ajouter le fichier de workflow à votre référentiel GitHub

Ajouter un fichier de définition d’API au dépôt

Vérifier l’inscription de l’API

Ajouter une nouvelle version d’API

Étendre le scénario

Contenu connexe

Commentaires

Ressources supplémentaires