Registrieren von APIs im API Center mithilfe von GitHub-Aktionen

In diesem Artikel wird gezeigt, wie Sie einen einfachen GitHub-Aktionen-Workflow einrichten, um eine API im API Center Ihrer Organisation zu registrieren. Die Registrierung tritt auf, wenn eine API-Spezifikationsdatei einem GitHub-Repository 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 mit einem GitHub Actions-Workflow automatisiert werden kann.

Der Prozess umfasst die folgenden Schritte:

Richten Sie einen GitHub Actions-Workflow in Ihrem Repository ein, der ausgelöst wird, wenn eine Pullanforderung, die eine API-Definitionsdatei hinzufügt, zusammengeführt wird.
Erstellen Sie einen Zweig vom Hauptzweig in Ihrem GitHub-Repository.
Fügen Sie eine API-Definitionsdatei hinzu, schreiben Sie die Änderungen fest und laden Sie sie in den neuen Branch hoch.
Erstellen Sie eine Pull-Anfrage, um den neuen Branch in den Hauptzweig zusammenzuführen.
Führen Sie den Pull Request zusammen.
Die Zusammenführung löst einen GitHub Actions-Workflow aus, der die API im API Center registriert.

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.

Voraussetzungen

Ein API-Center in Ihrem Azure-Abonnement. Sie können ein API-Center erstellen, indem Sie das Verfahren in der Schnellstartanleitung ausführen: Erstellen Sie Ihr API Center (Azure-Portal).>
Berechtigungen zum Erstellen eines Dienstprinzipals im Microsoft Entra ID-Mandanten.
Ein GitHub-Konto und ein GitHub-Repository, in dem Sie geheime Schlüssel und GitHub-Aktionen-Workflows konfigurieren können.
Für die Azure CLI:
- Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter "Erste Schritte mit 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. Weitere Anmeldeoptionen finden Sie unter Authentifizieren bei Azure mithilfe 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 und Verwalten 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 die az apic Befehle ist die apic-extension Azure CLI-Erweiterung erforderlich. Die Erweiterung kann dynamisch installiert werden, wenn Sie den ersten az apic Befehl ausführen, oder Sie können die Erweiterung manuell installieren. Weitere Informationen finden Sie unter Verwalten von Azure CLI-Erweiterungen: Installieren, Aktualisieren und Entfernen.

Die neuesten Änderungen und Updates finden Sie in apic-extensionden Versionshinweisen. Für bestimmte Features ist möglicherweise eine Vorschau oder eine bestimmte Version der Erweiterung erforderlich.

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

Mit den folgenden Schritten erstellen Sie einen Microsoft Entra ID-Dienst-Principal, der verwendet wird, um Anmeldeinformationen zum Workflow hinzuzufügen und sich bei Azure zu authentifizieren.

Hinweis

Die Konfiguration eines Diensthauptbenutzers wird zu Demonstrationszwecken dargestellt. Die empfohlene Methode zum Authentifizieren bei Azure für GitHub Actions ist OpenID Connect, eine Authentifizierungsmethode, die kurzlebige Token verwendet. Einrichten von OpenID Connect mit GitHub Actions ist komplexer, bietet jedoch mehr Sicherheit. Weitere Informationen finden Sie unter Deploy to Azure App Service by using GitHub Actions – Generate deployment credentials for OpenID Connect.

Erstellen Sie einen Dienstprinzipal mithilfe des az ad sp create-for-rbac-Befehls. Im folgenden Beispiel wird zuerst der Befehl az apic show zum Abrufen der Ressourcen-ID des API Center verwendet. Der Dienstprinzipal wird dann mit der Rolle „Mitwirkender für den Azure API Center-Dienst“ für das API-Center erstellt.

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

Kopieren Sie die JSON-Ausgabe, die dem folgenden Beispiel ähnelt:

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

Fügen Sie das Dienstprinzipal als GitHub-Geheimnis hinzu

Nachdem Sie über den Dienstprinzipal verfügen, fügen Sie ihn als GitHub-Geheimschlüssel hinzu:

Navigieren Sie in GitHub zu Ihrem Repository, und wählen Sie " Einstellungen " in der oberen Menüleiste aus.
Wählen Sie im linken Navigationsbereich unter "Sicherheit" die Option "Geheime Schlüssel" und "Variablenaktionen>" aus.
Wählen Sie New repository secret (Neues Repositorygeheimnis) aus.
Fügen Sie im Feld "Geheim" die gesamte JSON-Ausgabe aus dem Azure CLI-Befehl ein. Für den Namen, geben Sie AZURE_CREDENTIALS ein. 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 in einer YAML-Definitionsdatei (.yml) angegeben. Diese Definition enthält die verschiedenen Schritte und Parameter, die den Workflow bilden. Weitere Informationen finden Sie unter Workflowsyntax für GitHub-Aktionen.

Im folgenden Beispiel wird eine grundlegende Workflowdatei bereitgestellt, die Sie verwenden oder ändern können.

Der Workflow wird ausgelöst, wenn eine Pullanforderung, die eine JSON-Definition im APIs Pfad hinzufügt, in der Hauptzweigung geschlossen wird.
Der Speicherort der Definition wird aus der Pullanforderung mithilfe eines GitHub-Skripts extrahiert, das mit dem Standardmäßigen GitHub-Token authentifiziert wird.
Die in Ihrem Repository gespeicherten Azure-Anmeldeinformationen werden verwendet, um sich bei Azure anzumelden.
Der Befehl az apic register registriert die API im API Center, das in den Umgebungsvariablen angegeben ist.

Führen Sie die folgenden Schritte aus, um die Workflowdatei zu konfigurieren:

Kopieren und speichern Sie die Datei unter einem Namen wie register-api.yml.
Bestätigen oder aktualisieren Sie den Namen des Repositoryordners (APIs), in dem Sie die API-Definitionsdatei hinzufügen möchten.
Fügen Sie diese Workflowdatei im Pfad /.github/workflows/ in Ihrem GitHub-Repository hinzu.
Legen Sie die AktionsvariablenSERVICE_NAME und RESOURCE_GROUP im Repository für ihren API-Center-Namen und den Ressourcengruppennamen in Azure fest.

Tipp

Mithilfe der Visual Studio Code-Erweiterung für Azure API Center können Sie eine Startworkflowdatei generieren, indem Sie einen Erweiterungsbefehl ausführen. Geben Sie in der Befehlspalette (STRG+UMSCHALT+P) Das Azure API Center ein: Api registrieren und CI/CD>GitHub auswählen. Anschließend können Sie die Datei für Ihr Szenario anpassen oder erweitern.

Dies ist die Beispielworkflowdatei:

name: Register API Definition to Azure API Center
on:
  pull_request:
    types: [ closed ]
    branches:
      - [ "main" ]
    paths:
      - "APIs/**/*.json"
permissions:
  contents: read
  pull-requests: read
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', filename);
              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 ${{ vars.RESOURCE_GROUP }} -n ${{ vars.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-Filialen finden Sie in der GitHub-Dokumentation zu Entwicklungsmodellen für die Zusammenarbeit .

Erstellen Sie eine neue Arbeitsverzweigung aus dem Mainbranch in Ihrem GitHub-Repository.
Fügen Sie die API-Definitionsdatei zum Repository im APIs-Pfad hinzu. Beispiel: APIs/catfacts-api/07-15-2024.json.
Übernehmen Sie die Änderungen und laden Sie sie in den Arbeitsbranch hoch.
Erstellen Sie einen Pull-Request, um den Feature-Branch in den Hauptbranch zusammenzuführen.
Nach der Überprüfung den Pull Request zusammenführen. 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.

Navigieren Sie im Azure-Portal zum API Center.
Erweitern Sie im linken Navigationsbereich den Abschnitt " Bestand ", und wählen Sie "Objekte" aus.
Überprüfen Sie, ob die neu registrierte API in der Liste angezeigt wird.

Screenshot einer neuen API, die im API Center registriert ist, nachdem der Workflow ausgeführt wurde.

Hinzufügen einer neuen API-Version

Sie können einer vorhandenen API im API Center eine neue Version hinzufügen, indem Sie die gleichen Schritte mit einer geringfügigen Änderung ausführen.

Wechseln Sie zu derselben Arbeitsverzweigung in Ihrem Repository, oder erstellen Sie eine neue Arbeitsverzweigung.
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.
Übernehmen Sie die Änderungen und laden Sie sie in den Arbeitsbranch hoch.
Erstellen Sie einen Pull-Request, um den Feature-Branch in den Hauptbranch zusammenzuführen.
Nach der Überprüfung den Pull Request zusammenführen. Die Zusammenführung löst den GitHub Actions-Workflow aus, der die neue API-Version im API Center registriert.
Navigieren Sie im Azure-Portal zu Ihrem API Center, und vergewissern Sie sich, dass die neue Version für die API registriert ist.

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:

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": "admin-user@contoso.com",
  "team": "Store API dev team",
  "costCenter": "12345"  
}
```
Laden Sie für jede API im Repository eine JSON-Metadatendatei in den Ordner hoch.
Fügen Sie einen Workflowschritt hinzu, um die Metadaten auf die API-Registrierung mithilfe des Az apic-API-Aktualisierungsbefehls 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 ${{ vars.RESOURCE_GROUP }} -n ${{ vars.SERVICE_NAME }} --api-id {{ env.API_ID }} --custom-properties {{ env.METADATA_FILE }}
```

Feedback

War diese Seite hilfreich?

Last updated on 2026-02-26