Registrieren von APIs in Ihrem API Center mithilfe von GitHub Actions

In diesem Artikel wird gezeigt, wie Sie einen grundlegenden GitHub Actions-Workflow einrichten, um eine API im API Center Ihrer Organisation zu registrieren, wenn einem GitHub-Repository eine API-Spezifikationsdatei hinzugefügt wird.

Die Verwendung eines GitHub Actions-Workflows zum Registrieren von APIs im API Center ermöglicht einen konsistenten und wiederholbaren CI/CD-Prozess für jede neue oder aktualisierte API. Der Workflow kann erweitert werden, um Schritte wie das Hinzufügen von Metadaten zur API-Registrierung einzuschließen.

Das folgende Diagramm zeigt, wie die API-Registrierung in Ihrem API Center mithilfe eines GitHub Actions-Workflows automatisiert werden kann.

1. Richten Sie einen GitHub Actions-Workflow in Ihrem Repository ein, der ausgelöst wird, wenn ein Pull Request, der eine API-Definitionsdatei hinzufügt, zusammengeführt wird.
2. Erstellen Sie einen Branch aus dem Mainbranch in Ihrem GitHub-Repository.
3. Fügen Sie eine API-Definitionsdatei hinzu, committen Sie die Änderungen, und pushen Sie sie an den neuen Branch.
4. Erstellen Sie einen Pull Request, um den neuen Branch im Mainbranch zusammenzuführen.
5. Führen Sie den Pull Request zusammen.
6. Die Zusammenführung löst einen GitHub Actions-Workflow aus, der die API im API Center registriert.

Voraussetzungen

• Ein API-Center in Ihrem Azure-Abonnement. Wenn Sie noch keins erstellt haben, lesen Sie die Schnellstartanleitung: Erstellen Ihres API-Centers.

• Berechtigungen zum Erstellen eines Dienstprinzipals im Microsoft Entra ID-Mandanten

• Ein GitHub-Konto und ein GitHub-Repository, in dem Sie Geheimnisse und GitHub Actions-Workflows konfigurieren können

• Für die Azure CLI:

  • Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.

    

  • Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

    • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

    • Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.

    • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

  Hinweis

  Für az apic-Befehle wird die Azure CLI-Erweiterung apic-extension benötigt. Wenn Sie keine az apic-Befehle verwendet haben, kann die Erweiterung dynamisch installiert werden, wenn Sie den ersten az apic-Befehl ausführen. Sie können die Erweiterung auch manuell installieren. Hier finden Si weitere Informationen zu Azure CLI-Erweiterungen.

  In den Versionshinweisen finden Sie die neuesten Änderungen und Updates in der apic-extension.

  Hinweis

  Azure CLI-Befehlsbeispiele in diesem Artikel können in PowerShell oder einer Bash-Shell ausgeführt werden. Bei Bedarf aufgrund unterschiedlicher Variablensyntax werden separate Befehlsbeispiele für die beiden Shells bereitgestellt.

Einrichten eines GitHub Actions-Workflows

In diesem Abschnitt richten Sie den GitHub Actions-Workflow für dieses Szenario ein:

• Erstellen eines Dienstprinzipals, der für Azure-Anmeldeinformationen im Workflow verwendet werden soll
• Hinzufügen der Anmeldeinformationen als Geheimnis in Ihrem GitHub-Repository
• Konfigurieren eines GitHub Actions-Workflows, der ausgelöst wird, wenn ein Pull Request, der eine API-Definitionsdatei hinzufügt, zusammengeführt wird. Die Workflow-YAML-Datei enthält einen Schritt, der die Azure CLI zum Registrieren der API im API Center aus der Definitionsdatei verwendet.

Einrichten eines Dienstprinzipalgeheimnisses

Erstellen Sie in den folgenden Schritten einen Microsoft Entra ID-Dienstprinzipal, der zum Hinzufügen von Anmeldeinformationen zum Workflow zur Authentifizierung bei Azure verwendet wird.

Erstellen Sie mit dem Befehl az ad sp create-for-rbac einen Dienstprinzipal. Im folgenden Beispiel wird zuerst der Befehl az apic show zum Abrufen der Ressourcen-ID des API Center verwendet. Anschließend wird der Dienstprinzipal mit der Rolle „Mitwirkender“ für das API Center erstellt.

#! /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 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 Contributor --scopes $apicResourceId --json-auth

Kopieren Sie die JSON-Ausgabe, die etwa wie folgt aussehen sollte:

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

Hinzufügen des Dienstprinzipals als GitHub-Geheimnis

1. Suchen Sie auf GitHub nach Ihrem Repository. Wählen Sie Einstellungen aus.

2. Wählen Sie unter Sicherheit die Optionen Geheimnisse und Variablen>Aktionen aus.

3. Wählen Sie New repository secret (Neues Repositorygeheimnis) aus.

4. Fügen Sie die gesamte JSON-Ausgabe aus dem Azure CLI-Befehl in das Wertfeld des Geheimnisses ein. Geben Sie dem Geheimnis den Namen AZURE_CREDENTIALS. Klicken Sie auf Add secret (Geheimnis hinzufügen).

   Das Geheimnis wird unter Repositorygeheimnisse aufgeführt.

   

Wenn Sie später die GitHub-Workflowdatei konfigurieren, verwenden Sie das Geheimnis für den eingegebenen creds-Wert der Aktion Azure/login. Zum Beispiel:

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

Hinzufügen der Workflowdatei zum GitHub-Repository

Ein GitHub Actions-Workflow wird durch eine YAML-Definitionsdatei (.yml) dargestellt. Diese Definition enthält die verschiedenen Schritte und Parameter, die den Workflow bilden. Weitere Informationen

Im Anschluss sehen Sie eine einfache Workflowdatei für dieses Beispiel, die Sie verwenden oder ändern können.

In diesem Beispiel:

• Der Workflow wird ausgelöst, wenn ein Pull Request, der eine JSON-Definition im APIs-Pfad hinzufügt, im Mainbranch geschlossen wird.
• Der Speicherort der Definition wird aus dem Pull Request mithilfe eines GitHub-Skripts extrahiert, das mit dem GitHub-Standardtoken authentifiziert wird.
• Die in Ihrem Repository gespeicherten Azure-Anmeldeinformationen werden für die Anmeldung bei Azure verwendet.
• Der Befehl az apic register registriert die API im API Center, das in den Umgebungsvariablen angegeben ist.

So konfigurieren Sie die Workflowdatei

1. Kopieren und speichern Sie die Datei unter einem Namen wie register-api.yml.
2. Aktualisieren Sie die Werte für die Umgebungsvariablen so, dass sie Ihrem API Center in Azure entsprechen.
3. Bestätigen oder aktualisieren Sie den Namen des Repositoryordners (APIs), in dem Sie die API-Definitionsdatei hinzufügen.
4. Fügen Sie diese Workflowdatei im Pfad /.github/workflows/ in Ihrem GitHub-Repository hinzu.

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 }}

Hinzufügen einer API-Definitionsdatei zum Repository

Testen Sie den Workflow, indem Sie dem Repository eine API-Definitionsdatei hinzufügen. Führen Sie diese allgemeinen Schritte aus, die typisch für einen Entwicklungsworkflow sind. Ausführliche Informationen zum Arbeiten mit GitHub-Branches finden Sie in der GitHub-Dokumentation.

1. Erstellen Sie eine neue Arbeitsverzweigung aus dem Mainbranch in Ihrem GitHub-Repository.

2. Fügen Sie die API-Definitionsdatei zum Repository im APIs-Pfad hinzu. Beispiel: APIs/catfacts-api/07-15-2024.json.

3. Committen Sie die Änderungen, und pushen Sie sie an die Arbeitsverzweigung.

4. Erstellen Sie einen Pull Request, um die Arbeitsverzweigung im Mainbranch zusammenzuführen.

5. Führen Sie den Pull Request nach der Überprüfung zusammen. Die Zusammenführung löst den GitHub Actions-Workflow aus, der die API im API Center registriert.

   

Überprüfen der API-Registrierung

Überprüfen Sie, ob die API im API-Center registriert ist.

1. Navigieren Sie im Azure-Portal zu Ihrem API Center.
2. Wählen Sie im linken Menü unter Ressourcen die Option APIs aus.
3. Überprüfen Sie, ob die neu registrierte API in der Liste der APIs angezeigt wird.

Hinzufügen einer neuen API-Version

Wenn Sie einer vorhandenen API im API Center eine neue Version hinzufügen möchten, führen Sie die oben genannten Schritte mit einer geringfügigen Änderung aus:

1. Wechseln Sie zu derselben Arbeitsverzweigung in Ihrem Repository, oder erstellen Sie eine neue Arbeitsverzweigung.
2. Fügen Sie dem Repository im APIs-Pfad im Ordner für eine vorhandene API eine neue API-Definitionsdatei hinzu. Wenn Sie z. B. zuvor eine Cat Facts-API-Definition hinzugefügt haben, fügen Sie eine neue Version wie APIs/catfacts-api/07-22-2024.json hinzu.
3. Committen Sie die Änderungen, und pushen Sie sie an die Arbeitsverzweigung.
4. Erstellen Sie einen Pull Request, um die Arbeitsverzweigung im Mainbranch zusammenzuführen.
5. Führen Sie den Pull Request nach der Überprüfung zusammen. Die Zusammenführung löst den GitHub Actions-Workflow aus, der die neue API-Version im API Center registriert.
6. Navigieren Sie im Azure-Portal zum API Center, und überprüfen Sie, ob die neue Version registriert wurde.

Erweitern des Szenarios

Sie können den GitHub Actions-Workflow erweitern, um weitere Schritte einzuschließen, z. B. das Hinzufügen von Metadaten für die API-Registrierung. Zum Beispiel:

1. Erstellen Sie mithilfe des Metadatenschemas im API Center eine JSON-Metadatendatei, um Metadatenwerte auf Ihre API-Registrierung anzuwenden.

   Wenn das Metadatenschema beispielsweise Eigenschaften wie approver, team und cost center enthält, sieht eine JSON-Metadatendatei wie folgt aus:

   {
     "approver": "diego@contoso.com",
     "team": "Store API dev team",
     "costCenter": "12345"  
   }
   

2. Laden Sie für jede API im Repository eine JSON-Metadatendatei in den Ordner hoch.

3. Fügen Sie einen Workflowschritt hinzu, um die Metadaten mithilfe des Befehls az apic api update auf die API-Registrierung anzuwenden. Im folgenden Beispiel werden die API-ID und die Metadatendatei in Umgebungsvariablen übergeben, die an anderer Stelle in der Workflowdatei festgelegt werden.

   [...]
   - 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 }}
   

Zugehöriger Inhalt

• Verwenden von Geheimnissen in GitHub Actions
• Erstellen von Konfigurationsvariablen für ein Repository