API-k regisztrálása az API-központban a GitHub Actions használatával

Ez a cikk bemutatja, hogyan állíthat be egy alapszintű GitHub Actions-munkafolyamatot , amely regisztrál egy API-t a szervezet API-központjában , amikor hozzáad egy API-specifikációs fájlt egy GitHub-adattárhoz.

Az API-k API-k api-knak az API-központban való regisztrálására szolgáló GitHub Actions-munkafolyamat konzisztens és megismételhető CI/CD-folyamatot biztosít minden új vagy frissített API-hoz. A munkafolyamat kiterjeszthető olyan lépésekre is, mint például metaadatok hozzáadása az API-regisztrációhoz.

Az alábbi ábra bemutatja, hogyan automatizálható az API-regisztráció az API-központban egy GitHub Actions-munkafolyamat használatával.

1. Állítson be egy GitHub Actions-munkafolyamatot az adattárban, amely egy API-definíciós fájl összevonásakor aktiválódik.
2. Hozzon létre egy ágat a GitHub-adattár fő ágából.
3. Adjon hozzá egy API-definíciós fájlt, véglegesítse a módosításokat, és küldje el az új ágat.
4. Hozzon létre egy lekéréses kérelmet, amely egyesíti az új ágat a főágban.
5. A lekéréses kérelem egyesítése.
6. Az egyesítés elindít egy GitHub Actions-munkafolyamatot, amely regisztrálja az API-t az API-központban.

Előfeltételek

• Egy API-központ az Azure-előfizetésben. Ha még nem hozott létre egyet, olvassa el az API-központ létrehozása című rövid útmutatót.

• Szolgáltatásnév létrehozásához szükséges engedélyek a Microsoft Entra ID-bérlőben

• Egy GitHub-fiók és egy GitHub-adattár, amelyben titkos kulcsokat és GitHub Actions-munkafolyamatokat konfigurálhat

• Azure CLI esetén:

  • Használja a Bash-környezetet az Azure Cloud Shellben. További információ: A Bash rövid útmutatója az Azure Cloud Shellben.

    

  • Ha inkább helyi cli-referenciaparancsokat szeretne futtatni, telepítse az Azure CLI-t. Ha Windows vagy macOS rendszert használ, fontolja meg az Azure CLI Docker-tárolóban való futtatását. További információ: Az Azure CLI futtatása Docker-tárolóban.

    • Ha helyi telepítést használ, jelentkezzen be az Azure CLI-be az az login parancs futtatásával. A hitelesítési folyamat befejezéséhez kövesse a terminálon megjelenő lépéseket. További bejelentkezési lehetőségekért lásd : Bejelentkezés az Azure CLI-vel.

    • Amikor a rendszer kéri, először telepítse az Azure CLI-bővítményt. További információ a bővítményekről: Bővítmények használata az Azure CLI-vel.

    • Futtassa az az version parancsot a telepített verzió és a függő kódtárak megkereséséhez. A legújabb verzióra az az upgrade paranccsal frissíthet.

  Feljegyzés

  az apic parancsokhoz az apic-extension Azure CLI-bővítmény szükséges. Ha még nem használt az apic parancsokat, a bővítmény dinamikusan telepíthető az első az apic parancs futtatásakor, vagy manuálisan is telepítheti a bővítményt. További információ az Azure CLI-bővítményekről.

  A legújabb módosításokról és frissítésekről a kibocsátási megjegyzésekben olvashat.apic-extension Bizonyos funkciókhoz szükség lehet a bővítmény előzetes verziójára vagy adott verziójára.

  Feljegyzés

  A cikkben szereplő Azure CLI-parancsok PowerShellben vagy bash-rendszerhéjban futtathatók. A különböző változószintaxis miatt szükség esetén a két rendszerhéjhoz külön parancs példákat biztosítunk.

GitHub Actions-munkafolyamat beállítása

Ebben a szakaszban a GitHub Actions munkafolyamatot állítja be ehhez a forgatókönyvhöz:

• Hozzon létre egy szolgáltatásnevet, amelyet azure-beli hitelesítő adatokhoz használhat a munkafolyamatban.
• Adja hozzá a hitelesítő adatokat titkos kulcsként a GitHub-adattárban.
• Konfiguráljon egy GitHub Actions-munkafolyamatot, amely egy API-definíciós fájlt tartalmazó lekéréses kérelem egyesítésekor aktiválódik. A munkafolyamat YAML-fájlja tartalmaz egy lépést, amely az Azure CLI használatával regisztrálja az API-t az API-központban a definíciós fájlból.

Szolgáltatásnév titkos kód beállítása

A következő lépésekben hozzon létre egy Microsoft Entra ID szolgáltatásnevet, amely hitelesítő adatokat ad hozzá a munkafolyamathoz az Azure-ral való hitelesítéshez.

Hozzon létre egy szolgáltatásnevet az az ad sp create-for-rbac paranccsal. Az alábbi példa először az az apic show paranccsal kéri le az API-központ erőforrás-azonosítóját. A szolgáltatásnév ezután az API-központ Azure API Center szolgáltatás közreműködői szerepkörével jön létre.

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

Másolja ki a JSON-kimenetet, amelynek a következőhöz hasonlóan kell kinéznie:

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

A szolgáltatásnév hozzáadása GitHub-titkos kódként

1. A GitHubon tallózzon az adattárban. Válassza a Beállítások lehetőséget.

2. A Biztonság területen válassza a Titkos kódok és változók>műveletek lehetőséget

3. Válassza az Új tárház titkos kódját.

4. Illessze be az Azure CLI parancs teljes JSON-kimenetét a titkos kód értékmezőjébe. Nevezze el a titkos kulcsot AZURE_CREDENTIALS. Válassza az Add secret (Titkos kód hozzáadása) lehetőséget.

   A titkos kód az adattár titkos kulcsainak listájában található.

   

Amikor később konfigurálja a GitHub-munkafolyamatfájlt, a titkos kulcsot használja az Azure/bejelentkezési művelet bemenetéhezcreds. Példa:

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

Munkafolyamat-fájl hozzáadása a GitHub-adattárhoz

A GitHub Actions-munkafolyamatokat yaML-definíciós fájl (.yml) jelöli. Ez a definíció a munkafolyamatot alkotó különböző lépéseket és paramétereket tartalmazza. További információ

A következő egy egyszerű munkafolyamat-fájl ehhez a példához, amelyet használhat vagy módosíthat.

Ebben a példában:

• A munkafolyamat akkor aktiválódik, ha egy JSON-definíciót az elérési úthoz APIs hozzáadó lekéréses kérelem lezárul a főágon.
• A definíció helyét egy GitHub-szkripttel nyeri ki a lekéréses kérelemből, amelyet az alapértelmezett GitHub-jogkivonat hitelesít.
• Az adattárban mentett Azure-hitelesítő adatokkal lehet bejelentkezni az Azure-ba.
• Az az apic register parancs regisztrálja az API-t a környezeti változókban megadott API-központban.

A munkafolyamat-fájl konfigurálása:

1. Másolja és mentse a fájlt egy olyan név alatt, mint a register-api.yml.
2. Erősítse meg vagy frissítse annak az adattármappának (APIs) a nevét, amelyben hozzá fogja adni az API-definíciós fájlt.
3. Adja hozzá ezt a munkafolyamat-fájlt a /.github/workflows/ GitHub-adattár elérési útjához.
4. Állítsa be az Actions változókatSERVICE_NAME és RESOURCE_GROUP az adattárban az API-központ nevét és az erőforráscsoport nevét az Azure-ban.

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

API-definíciós fájl hozzáadása az adattárhoz

Tesztelje a munkafolyamatot úgy, hogy hozzáad egy API-definíciós fájlt az adattárhoz. Kövesse ezeket a magas szintű lépéseket, amelyek általában egy fejlesztési munkafolyamatra jellemzőek. A GitHub-ágakkal való munkával kapcsolatos részletekért tekintse meg a GitHub dokumentációját.

1. Hozzon létre egy új munkaágat az adattár fő ágából.

2. Adja hozzá az API-definíciós fájlt az elérési út adattárához APIs . Például: APIs/catfacts-api/07-15-2024.json.

3. Véglegesítse a módosításokat, és küldje el őket a munkaágba.

4. Hozzon létre egy lekéréses kérelmet a munkaág fő ágba való egyesítéséhez.

5. A felülvizsgálat után egyesítse a lekéréses kérelmet. Az egyesítés aktiválja a GitHub Actions munkafolyamatot, amely regisztrálja az API-t az API-központban.

   

Az API-regisztráció ellenőrzése

Ellenőrizze, hogy az API regisztrálva van-e az API-központban.

1. Az Azure Portalon keresse meg az API-központot.
2. A bal oldali menü Eszközök területén válassza az API-kat.
3. Ellenőrizze, hogy az újonnan regisztrált API megjelenik-e az API-k listájában.

Új API-verzió hozzáadása

Ha új verziót szeretne hozzáadni egy meglévő API-hoz az API-központban, kövesse az alábbi lépéseket egy kis módosítással:

1. Váltson ugyanarra a munkaágra az adattárban, vagy hozzon létre egy új munkaágat.
2. Adjon hozzá egy új API-definíciós fájlt az APIs elérési út adattárához egy meglévő API mappájában. Ha például korábban hozzáadott egy Cat Facts API-definíciót, adjon hozzá egy új verziót, például APIs/catfacts-api/07-22-2024.json.
3. Véglegesítse a módosításokat, és küldje el őket a munkaágba.
4. Hozzon létre egy lekéréses kérelmet a munkaág fő ágba való egyesítéséhez.
5. A felülvizsgálat után egyesítse a lekéréses kérelmet. Az egyesítés aktiválja a GitHub Actions munkafolyamatot, amely regisztrálja az új API-verziót az API-központban.
6. Az Azure Portalon lépjen az API-központba, és győződjön meg arról, hogy az új verzió regisztrálva van.

A forgatókönyv kiterjesztése

A GitHub Actions munkafolyamatot kiterjesztheti más lépésekre is, például metaadatok hozzáadására az API-regisztrációhoz. Példa:

1. Az API-központ metaadat-sémájának használatával hozzon létre egy metaadat-JSON-fájlt, amely metaadat-értékeket alkalmaz az API-regisztrációra.

   Ha például a metaadat-séma olyan tulajdonságokat tartalmaz, mint approverpéldául a , teamés cost centera metaadat JSON-fájl, a következőképpen nézhet ki:

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

2. Töltsön fel egy metaadat JSON-fájlt az adattár minden API-jának mappájába.

3. Adjon hozzá egy munkafolyamat-lépést a metaadatok API-regisztrációra való alkalmazásához az az apic api update paranccsal. Az alábbi példában az API-azonosító és a metaadatfájl környezeti változókban lesz átadva, amelyek a munkafolyamat-fájl más részén lennének beállítva.

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

Kapcsolódó tartalom

• Titkos kódok használata a GitHub Actionsben
• Konfigurációs változók létrehozása adattárhoz