API's registreren in uw API-centrum met behulp van GitHub Actions

Artikel
07/25/2024

In dit artikel wordt beschreven hoe u een eenvoudige Werkstroom voor GitHub Actions instelt voor het registreren van een API in het API-centrum van uw organisatie wanneer een API-specificatiebestand wordt toegevoegd aan een GitHub-opslagplaats.

Het gebruik van een GitHub Actions-werkstroom voor het registreren van API's in uw API-centrum biedt een consistent en herhaalbaar CI/CD-proces voor elke nieuwe of bijgewerkte API. De werkstroom kan worden uitgebreid met stappen zoals het toevoegen van metagegevens aan de API-registratie.

In het volgende diagram ziet u hoe API-registratie in uw API-centrum kan worden geautomatiseerd met behulp van een GitHub Actions-werkstroom.

Stel een GitHub Actions-werkstroom in uw opslagplaats in die wordt geactiveerd wanneer een pull-aanvraag waarmee een API-definitiebestand wordt toegevoegd, wordt samengevoegd.
Maak een vertakking van de hoofdbranch in uw GitHub-opslagplaats.
Voeg een API-definitiebestand toe, voer de wijzigingen door en push ze naar de nieuwe vertakking.
Maak een pull-aanvraag om de nieuwe vertakking samen te voegen in de hoofdbranch.
Voeg de pull-aanvraag samen.
Met de samenvoegbewerking wordt een GitHub Actions-werkstroom geactiveerd waarmee de API in uw API-centrum wordt geregistreerd.

Vereisten

Een API-centrum in uw Azure-abonnement. Als u er nog geen hebt gemaakt, raadpleegt u quickstart: Uw API-centrum maken.
Machtigingen voor het maken van een service-principal in de Microsoft Entra ID-tenant
Een GitHub-account en een GitHub-opslagplaats waarin u geheimen en GitHub Actions-werkstromen kunt configureren
Voor Azure CLI:
- Gebruik de Bash-omgeving in Azure Cloud Shell. Zie quickstart voor Bash in Azure Cloud Shell voor meer informatie.
- Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.
  - Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.
  - Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.
  - Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.
Notitie

az apic voor opdrachten is de apic-extension Azure CLI-extensie vereist. Als u geen opdrachten hebt gebruikt az apic , kan de extensie dynamisch worden geïnstalleerd wanneer u uw eerste az apic opdracht uitvoert of kunt u de extensie handmatig installeren. Meer informatie over Azure CLI-extensies.

Zie de releaseopmerkingen voor de meest recente wijzigingen en updates in de apic-extension.

Notitie

Voorbeelden van Azure CLI-opdrachten in dit artikel kunnen worden uitgevoerd in PowerShell of een bash-shell. Indien nodig vanwege verschillende syntaxis van variabelen, worden er afzonderlijke opdrachtvoorbeelden gegeven voor de twee shells.

Een GitHub Actions-werkstroom instellen

In deze sectie stelt u de GitHub Actions-werkstroom in voor dit scenario:

Maak een service-principal die moet worden gebruikt voor Azure-referenties in de werkstroom.
Voeg de referenties toe als een geheim in uw GitHub-opslagplaats.
Configureer een GitHub Actions-werkstroom die wordt geactiveerd wanneer een pull-aanvraag waarmee een API-definitiebestand wordt toegevoegd, wordt samengevoegd. Het YAML-werkstroombestand bevat een stap die gebruikmaakt van de Azure CLI om de API in uw API-centrum te registreren vanuit het definitiebestand.

Een geheim voor de service-principal instellen

Maak in de volgende stappen een Service-principal voor Microsoft Entra ID, die wordt gebruikt om referenties toe te voegen aan de werkstroom voor verificatie met Azure.

Notitie

Het configureren van een service-principal wordt weergegeven voor demonstratiedoeleinden. De aanbevolen manier om te verifiëren met Azure voor GitHub Actions is met OpenID Connect, een verificatiemethode die gebruikmaakt van kortdurende tokens. Het instellen van OpenID Connect met GitHub Actions is complexer, maar biedt beperkte beveiliging. Meer informatie

Maak een service-principal met behulp van de opdracht az ad sp create-for-rbac. In het volgende voorbeeld wordt eerst de opdracht az apic show gebruikt om de resource-id van het API-centrum op te halen. De service-principal wordt vervolgens gemaakt met de rol Azure API Center-servicebijdrager voor het API-centrum.

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

Kopieer de JSON-uitvoer, die er ongeveer als volgt uitziet:

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

De service-principal toevoegen als een GitHub-geheim

In GitHub, bladert u in uw opslagplaats. Selecteer Instellingen.
Selecteer onder Beveiliging geheimen en variabelenacties>
Selecteer Nieuw opslagplaatsgeheim.
Plak de volledige JSON-uitvoer van de Azure CLI-opdracht in het waardeveld van het geheim. Geef het geheim AZURE_CREDENTIALSeen naam. Selecteer Geheim toevoegen.

Het geheim wordt vermeld onder Opslagplaatsgeheimen.

Wanneer u het GitHub-werkstroombestand later configureert, gebruikt u het geheim voor de invoer creds van de Azure-/aanmeldingsactie . Voorbeeld:

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

Het werkstroombestand toevoegen aan uw GitHub-opslagplaats

Een GitHub Actions-werkstroom wordt vertegenwoordigd door een YAML-definitiebestand (.yml). Deze definitie bevat de verschillende stappen en parameters die deel uitmaken van de werkstroom. Meer informatie

Hier volgt een basiswerkstroombestand voor dit voorbeeld dat u kunt gebruiken of wijzigen.

In dit voorbeeld:

De werkstroom wordt geactiveerd wanneer een pull-aanvraag waarmee een JSON-definitie in het APIs pad wordt toegevoegd, wordt gesloten in de hoofdbranch.
De locatie van de definitie wordt geëxtraheerd uit de pull-aanvraag met behulp van een GitHub-script, dat wordt geverifieerd met het standaard GitHub-token.
De Azure-referenties die zijn opgeslagen in uw opslagplaats, worden gebruikt om u aan te melden bij Azure.
Met de opdracht az apic register wordt de API geregistreerd in het API-centrum dat is opgegeven in de omgevingsvariabelen.

Het werkstroombestand configureren:

Kopieer het bestand en sla het op onder een naam, zoals register-api.yml.
Werk de waarden voor de omgevingsvariabelen bij zodat deze overeenkomen met uw API-centrum in Azure.
Bevestig of werk de naam van de opslagplaatsmap (APIs) bij waar u het API-definitiebestand toevoegt.
Voeg dit werkstroombestand toe aan het /.github/workflows/ pad in uw GitHub-opslagplaats.

Tip

Met de Visual Studio Code-extensie voor Azure API Center kunt u een startwerkstroombestand genereren door een extensieopdracht uit te voeren. Selecteer Azure API Center in het opdrachtpalet: API's registreren. Selecteer CI/CD>GitHub. Vervolgens kunt u het bestand voor uw scenario wijzigen.

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

API-definitiebestand toevoegen aan de opslagplaats

Test de werkstroom door een API-definitiebestand toe te voegen aan de opslagplaats. Volg deze stappen op hoog niveau, die typisch zijn voor een ontwikkelwerkstroom. Zie de GitHub-documentatie voor meer informatie over het werken met GitHub-vertakkingen.

Maak een nieuwe werkbranch vanuit de hoofdbranch in uw opslagplaats.
Voeg het API-definitiebestand toe aan de opslagplaats in het APIs pad. Bijvoorbeeld: APIs/catfacts-api/07-15-2024.json.
Voer de wijzigingen door en push ze naar de werkbranch.
Maak een pull-aanvraag om de werkbranch samen te voegen in de hoofdbranch.
Voeg na beoordeling de pull-aanvraag samen. Met de samenvoegbewerking wordt de GitHub Actions-werkstroom geactiveerd waarmee de API in uw API-centrum wordt geregistreerd.

De API-registratie verifiëren

Controleer of de API is geregistreerd in uw API-centrum.

Navigeer in Azure Portal naar uw API-centrum.
Selecteer API's in het linkermenu onder Assets.
Controleer of de zojuist geregistreerde API wordt weergegeven in de lijst met API's.

Schermopname van DE API die is geregistreerd in API Center na de werkstroom.

Een nieuwe API-versie toevoegen

Als u een nieuwe versie wilt toevoegen aan een bestaande API in uw API-centrum, volgt u de voorgaande stappen, met een kleine wijziging:

Ga naar dezelfde werkvertakking in uw opslagplaats of maak een nieuwe werkvertakking.
Voeg een nieuw API-definitiebestand toe aan de opslagplaats in het APIs pad, in de map voor een bestaande API. Als u bijvoorbeeld eerder een Cat Facts API-definitie hebt toegevoegd, voegt u een nieuwe versie toe, zoals APIs/catfacts-api/07-22-2024.json.
Voer de wijzigingen door en push ze naar de werkbranch.
Maak een pull-aanvraag om de werkbranch samen te voegen in de hoofdbranch.
Voeg na beoordeling de pull-aanvraag samen. Met de samenvoegbewerking wordt de GitHub Actions-werkstroom geactiveerd waarmee de nieuwe API-versie in uw API-centrum wordt geregistreerd.
Navigeer in Azure Portal naar uw API-centrum en controleer of de nieuwe versie is geregistreerd.

Het scenario uitbreiden

U kunt de GitHub Actions-werkstroom uitbreiden met andere stappen, zoals het toevoegen van metagegevens voor de API-registratie. Voorbeeld:

Maak met behulp van het metagegevensschema in uw API-centrum een JSON-bestand met metagegevens om metagegevenswaarden toe te passen op uw API-registratie.

Als het metagegevensschema bijvoorbeeld eigenschappen bevat zoals approver, teamen cost center, kan een JSON-bestand met metagegevens er als volgt uitzien:
```
{
  "approver": "diego@contoso.com",
  "team": "Store API dev team",
  "costCenter": "12345"  
}
```
Upload een JSON-bestand met metagegevens in de map voor elke API in de opslagplaats.
Voeg een werkstroomstap toe om de metagegevens toe te passen op de API-registratie met behulp van de opdracht az apic api update . In het volgende voorbeeld worden de API-id en het metagegevensbestand doorgegeven in omgevingsvariabelen, die ergens anders in het werkstroombestand worden ingesteld.
```
[...]
- 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 }}
```

Delen via

API's registreren in uw API-centrum met behulp van GitHub Actions

Vereisten

Een GitHub Actions-werkstroom instellen

Een geheim voor de service-principal instellen

De service-principal toevoegen als een GitHub-geheim

Het werkstroombestand toevoegen aan uw GitHub-opslagplaats

API-definitiebestand toevoegen aan de opslagplaats

De API-registratie verifiëren

Een nieuwe API-versie toevoegen

Het scenario uitbreiden

Feedback

Aanvullende resources

Delen via

API's registreren in uw API-centrum met behulp van GitHub Actions

Vereisten

Een GitHub Actions-werkstroom instellen

Een geheim voor de service-principal instellen

De service-principal toevoegen als een GitHub-geheim

Het werkstroombestand toevoegen aan uw GitHub-opslagplaats

API-definitiebestand toevoegen aan de opslagplaats

De API-registratie verifiëren

Een nieuwe API-versie toevoegen

Het scenario uitbreiden

Gerelateerde inhoud

Feedback

Aanvullende resources