Dela via

Registrera API:er i api-centret med GitHub Actions

  • Artikel

Den här artikeln visar hur du konfigurerar ett grundläggande GitHub Actions-arbetsflöde för att registrera ett API i din organisations API Center när en API-specifikationsfil läggs till på en GitHub-lagringsplats.

Genom att använda ett GitHub Actions-arbetsflöde för att registrera API:er i DITT API Center får du en konsekvent och repeterbar CI/CD-process för varje nytt eller uppdaterat API. Arbetsflödet kan utökas till att omfatta steg som att lägga till metadata i API-registreringen.

Följande diagram visar hur API-registrering i DITT API Center kan automatiseras med hjälp av ett GitHub Actions-arbetsflöde.

Diagram som visar steg för att utlösa ett GitHub actions-arbetsflöde för att registrera ett API i ett Azure API-center.

  1. Konfigurera ett GitHub Actions-arbetsflöde på din lagringsplats som utlöses när en pull-begäran som lägger till en API-definitionsfil slås samman.
  2. Skapa en gren från huvudgrenen på din GitHub-lagringsplats.
  3. Lägg till en API-definitionsfil, checka in ändringarna och skicka dem till den nya grenen.
  4. Skapa en pull-begäran för att sammanfoga den nya grenen till huvudgrenen.
  5. Sammanfoga pull-begäran.
  6. Sammanfogningen utlöser ett GitHub Actions-arbetsflöde som registrerar API:et i api-centret.

Förutsättningar

  • Ett API-center i din Azure-prenumeration. Om du inte redan har skapat ett kan du läsa Snabbstart: Skapa ditt API-center.

  • Behörigheter för att skapa ett huvudnamn för tjänsten i Microsoft Entra ID-klientorganisationen

  • Ett GitHub-konto och en GitHub-lagringsplats där du kan konfigurera arbetsflöden för hemligheter och GitHub Actions

  • För Azure CLI:

    Kommentar

    az apic kommandon kräver Azure CLI-tillägget apic-extension . Om du inte har använt az apic kommandon kan tillägget installeras dynamiskt när du kör ditt första az apic kommando, eller så kan du installera tillägget manuellt. Läs mer om Azure CLI-tillägg.

    Se viktig information för de senaste ändringarna och uppdateringarna apic-extensioni .

    Kommentar

    Azure CLI-kommandoexempel i den här artikeln kan köras i PowerShell eller ett bash-gränssnitt. Vid behov på grund av olika variabelsyntax tillhandahålls separata kommandoexempel för de två gränssnitten.

Konfigurera ett GitHub Actions-arbetsflöde

I det här avsnittet konfigurerar du GitHub Actions-arbetsflödet för det här scenariot:

  • Skapa ett huvudnamn för tjänsten som ska användas för Azure-autentiseringsuppgifter i arbetsflödet.
  • Lägg till autentiseringsuppgifterna som en hemlighet på din GitHub-lagringsplats.
  • Konfigurera ett GitHub Actions-arbetsflöde som utlöses när en pull-begäran som lägger till en API-definitionsfil sammanfogas. YAML-arbetsflödesfilen innehåller ett steg som använder Azure CLI för att registrera API:et i API-centret från definitionsfilen.

Konfigurera en hemlighet för tjänstens huvudnamn

I följande steg skapar du ett Microsoft Entra ID-tjänsthuvudnamn som ska användas för att lägga till autentiseringsuppgifter i arbetsflödet för att autentisera med Azure.

Kommentar

Konfiguration av tjänstens huvudnamn visas i demonstrationssyfte. Det rekommenderade sättet att autentisera med Azure for GitHub Actions är med OpenID Connect, en autentiseringsmetod som använder kortlivade token. Att konfigurera OpenID Connect med GitHub Actions är mer komplext men ger förstärkt säkerhet. Läs mer

Skapa ett huvudnamn för tjänsten med kommandot az ad sp create-for-rbac. I följande exempel används först kommandot az apic show för att hämta resurs-ID:t för API Center. Tjänstens huvudnamn skapas sedan med rollen Azure API Center-tjänstdeltagare för API-centret.

#! /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

Kopiera JSON-utdata, som bör se ut ungefär så här:

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

Lägg till tjänstens huvudnamn som en GitHub-hemlighet

  1. I GitHub bläddrar du till lagringsplatsen. Välj Inställningar.

  2. Under Säkerhet väljer du Hemligheter och variabler>Åtgärder

  3. Välj Ny lagringsplatshemlighet.

  4. Klistra in hela JSON-utdata från Azure CLI-kommandot i hemlighetens värdefält. Ge hemligheten AZURE_CREDENTIALSnamnet . Välj Add secret (Lägg till hemlighet).

    Hemligheten visas under Lagringsplatshemligheter.

    Skärmbild av hemligheter för åtgärder på en GitHub-lagringsplats.

När du konfigurerar GitHub-arbetsflödesfilen senare använder du hemligheten för indata creds från azure-/inloggningsåtgärden. Till exempel:

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

Lägg till arbetsflödesfilen på din GitHub-lagringsplats

Ett GitHub Actions-arbetsflöde representeras av en YAML-definitionsfil (.yml). Den här definitionen innehåller de olika steg och parametrar som utgör arbetsflödet. Läs mer

Följande är en grundläggande arbetsflödesfil för det här exemplet som du kan använda eller ändra.

I det här exemplet:

  • Arbetsflödet utlöses när en pull-begäran som lägger till en JSON-definition i APIs sökvägen stängs på huvudgrenen.
  • Platsen för definitionen extraheras från pull-begäran med hjälp av ett GitHub-skript, som autentiseras med standard-GitHub-token.
  • De Azure-autentiseringsuppgifter som sparats på lagringsplatsen används för att logga in på Azure.
  • Kommandot az apic register registrerar API:et i API-centret som anges i miljövariablerna.

Så här konfigurerar du arbetsflödesfilen:

  1. Kopiera och spara filen under ett namn som register-api.yml.
  2. Uppdatera värdena för miljövariablerna så att de matchar api-centret i Azure.
  3. Bekräfta eller uppdatera namnet på den lagringsplatsmapp (APIs) där du lägger till API-definitionsfilen.
  4. Lägg till den här arbetsflödesfilen i /.github/workflows/ sökvägen på din GitHub-lagringsplats.

Dricks

Med hjälp av Visual Studio Code-tillägget för Azure API Center kan du generera en startarbetsflödesfil genom att köra ett tilläggskommando. I kommandopaletten väljer du Azure API Center: Registrera API:er. Välj CI/CD>GitHub. Du kan sedan ändra filen för ditt scenario.

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

Lägg till API-definitionsfil på lagringsplatsen

Testa arbetsflödet genom att lägga till en API-definitionsfil på lagringsplatsen. Följ dessa övergripande steg, som är typiska för ett utvecklingsarbetsflöde. Mer information om hur du arbetar med GitHub-grenar finns i GitHub-dokumentationen.

  1. Skapa en ny arbetsgren från huvudgrenen på lagringsplatsen.

  2. Lägg till API-definitionsfilen till lagringsplatsen i APIs sökvägen. Exempel: APIs/catfacts-api/07-15-2024.json

  3. Checka in ändringarna och push-överför dem till arbetsgrenen.

  4. Skapa en pull-begäran för att sammanfoga arbetsgrenen till huvudgrenen.

  5. Efter granskning sammanfogar du pull-begäran. Sammanfogningen utlöser det GitHub Actions-arbetsflöde som registrerar API:et i ditt API Center.

    Skärmbild som visar lyckad arbetsflödeskörning i GitHub.

Verifiera API-registreringen

Kontrollera att API:et är registrerat i api-centret.

  1. I Azure Portal går du till API-centret.
  2. I den vänstra menyn under Tillgångar väljer du API:er.
  3. Kontrollera att det nyligen registrerade API:et visas i listan över API:er.

Skärmbild av API som registrerats i API Center efter arbetsflödet.

Lägga till en ny API-version

Om du vill lägga till en ny version i ett befintligt API i api-centret följer du föregående steg med en liten ändring:

  1. Ändra till samma arbetsgren på lagringsplatsen eller skapa en ny arbetsgren.
  2. Lägg till en ny API-definitionsfil till lagringsplatsen i APIs sökvägen i mappen för ett befintligt API. Om du till exempel tidigare har lagt till en Cat Facts API-definition lägger du till en ny version som APIs/catfacts-api/07-22-2024.json.
  3. Checka in ändringarna och push-överför dem till arbetsgrenen.
  4. Skapa en pull-begäran för att sammanfoga arbetsgrenen till huvudgrenen.
  5. Efter granskning sammanfogar du pull-begäran. Sammanfogningen utlöser GitHub Actions-arbetsflödet som registrerar den nya API-versionen i DITT API Center.
  6. I Azure Portal går du till API-centret och bekräftar att den nya versionen är registrerad.

Utöka scenariot

Du kan utöka GitHub Actions-arbetsflödet så att det innehåller andra steg, till exempel att lägga till metadata för API-registreringen. Till exempel:

  1. Använd metadataschemat i API-centret och skapa en metadata-JSON-fil för att tillämpa metadatavärden för din API-registrering.

    Om metadataschemat till exempel innehåller egenskaper som approver, teamoch cost center, kan en metadata-JSON-fil se ut så här:

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

  2. Ladda upp en metadata-JSON-fil i mappen för varje API på lagringsplatsen.

  3. Lägg till ett arbetsflödessteg för att tillämpa metadata på API-registreringen med hjälp av kommandot az apic api update . I följande exempel skickas API-ID:t och metadatafilen i miljövariabler, som skulle anges någon annanstans i arbetsflödesfilen.

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

Relaterat innehåll