Registrace rozhraní API v centru rozhraní API pomocí GitHub Actions

Článek
07/25/2024

Tento článek ukazuje, jak nastavit základní pracovní postup GitHub Actions pro registraci rozhraní API v centru rozhraní API vaší organizace při přidání souboru specifikace rozhraní API do úložiště GitHub.

Použití pracovního postupu GitHub Actions k registraci rozhraní API v centru rozhraní API poskytuje konzistentní a opakovatelný proces CI/CD pro každé nové nebo aktualizované rozhraní API. Pracovní postup lze rozšířit tak, aby zahrnoval kroky, jako je přidání metadat do registrace rozhraní API.

Následující diagram ukazuje, jak můžete registraci rozhraní API v centru API automatizovat pomocí pracovního postupu GitHub Actions.

Nastavte v úložišti pracovní postup GitHub Actions, který se aktivuje, když se sloučí žádost o přijetí změn, která přidá definiční soubor rozhraní API.
Vytvořte větev z hlavní větve v úložišti GitHub.
Přidejte definiční soubor rozhraní API, potvrďte změny a nasdílejte je do nové větve.
Vytvořte žádost o přijetí změn pro sloučení nové větve do hlavní větve.
Sloučí žádost o přijetí změn.
Sloučení aktivuje pracovní postup GitHub Actions, který zaregistruje rozhraní API v centru rozhraní API.

Požadavky

Centrum rozhraní API ve vašem předplatném Azure. Pokud jste ho ještě nevytvořili, přečtěte si článek Rychlý start: Vytvoření centra rozhraní API.
Oprávnění k vytvoření instančního objektu v tenantovi Microsoft Entra ID
Účet GitHubu a úložiště GitHub, ve kterém můžete nakonfigurovat tajné kódy a pracovní postupy GitHub Actions
Pro Azure CLI:
- Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Rychlý start pro Bash v Azure Cloud Shellu.
- Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.
  - Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Přihlášení pomocí Azure CLI.
  - Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Využití rozšíření v Azure CLI.
  - Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.
Poznámka:

az apic příkazy vyžadují apic-extension rozšíření Azure CLI. Pokud jste nepoužili az apic příkazy, můžete rozšíření nainstalovat dynamicky při spuštění prvního az apic příkazu nebo rozšíření nainstalovat ručně. Přečtěte si další informace o rozšířeních Azure CLI.

Podívejte se na poznámky k verzi nejnovějších změn a aktualizací v nástroji apic-extension.

Poznámka:

Příklady příkazů Azure CLI v tomto článku se dají spustit v PowerShellu nebo prostředí Bash. Pokud je to potřeba kvůli jiné syntaxi proměnných, jsou pro tyto dvě prostředí k dispozici samostatné příklady příkazů.

Nastavení pracovního postupu GitHub Actions

V této části nastavíte pracovní postup GitHub Actions pro tento scénář:

Vytvořte instanční objekt, který se použije pro přihlašovací údaje Azure v pracovním postupu.
Přidejte přihlašovací údaje jako tajný klíč do úložiště GitHub.
Nakonfigurujte pracovní postup GitHub Actions, který se aktivuje, když se sloučí žádost o přijetí změn, která přidá definiční soubor rozhraní API. Soubor YAML pracovního postupu obsahuje krok, který pomocí Azure CLI zaregistruje rozhraní API v centru rozhraní API z definičního souboru.

Nastavení tajného kódu instančního objektu

V následujících krocích vytvořte instanční objekt Microsoft Entra ID, který se použije k přidání přihlašovacích údajů do pracovního postupu pro ověření v Azure.

Poznámka:

Konfigurace instančního objektu se zobrazí pro demonstrační účely. Doporučený způsob ověřování pomocí Azure for GitHub Actions je OpenID Connect, což je metoda ověřování, která používá krátkodobé tokeny. Nastavení OpenID Connect pomocí GitHub Actions je složitější, ale nabízí posílené zabezpečení. Další informace

Vytvořte instanční objekt pomocí příkazu az ad sp create-for-rbac. Následující příklad nejprve pomocí příkazu az apic show načte ID prostředku centra rozhraní API. Instanční objekt se pak vytvoří s rolí Přispěvatel služeb Azure API Center pro centrum rozhraní API.

Udeřit
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

Zkopírujte výstup JSON, který by měl vypadat nějak takto:

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

Přidání instančního objektu jako tajného kódu GitHubu

Na GitHubu přejděte do úložiště. Vyberte Nastavení.
V části Zabezpečení vyberte Akce tajných kódů a proměnných>.
Vyberte Nový tajný klíč úložiště.
Celý výstup JSON z příkazu Azure CLI vložte do pole hodnoty tajného kódu. Pojmenujte tajný kód AZURE_CREDENTIALS. Vyberte Add secret (Přidat tajný kód).

Tajný klíč je uvedený v části Tajné kódy úložiště.

Když později nakonfigurujete soubor pracovního postupu GitHubu, použijete tajný kód pro vstup creds akce Azure nebo přihlášení . Příklad:

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

Přidání souboru pracovního postupu do úložiště GitHub

Pracovní postup GitHub Actions je reprezentován definičním souborem YAML (.yml). Tato definice obsahuje různé kroky a parametry, které tvoří pracovní postup. Další informace

Následuje základní soubor pracovního postupu pro tento příklad, který můžete použít nebo upravit.

V tomto příkladu:

Pracovní postup se aktivuje, když se v hlavní větvi zavře žádost o přijetí změn, která do cesty přidá definici APIs JSON.
Umístění definice se extrahuje z žádosti o přijetí změn pomocí skriptu GitHubu, který se ověřuje pomocí výchozího tokenu GitHubu.
Přihlašovací údaje Azure uložené v úložišti se používají k přihlášení do Azure.
Příkaz az apic register zaregistruje rozhraní API v centru rozhraní API určeném v proměnných prostředí.

Konfigurace souboru pracovního postupu:

Zkopírujte a uložte soubor pod názvem, například register-api.yml.
Aktualizujte hodnoty proměnných prostředí tak, aby odpovídaly centru rozhraní API v Azure.
Potvrďte nebo aktualizujte název složky úložiště (APIs), do které přidáte definiční soubor rozhraní API.
Přidejte tento soubor pracovního postupu do /.github/workflows/ cesty v úložišti GitHub.

Tip

Pomocí rozšíření Visual Studio Code pro Azure API Center můžete vygenerovat spouštěcí soubor pracovního postupu spuštěním příkazu rozšíření. Na paletě příkazů vyberte Azure API Center: Registrace rozhraní API. Vyberte CI/CD>GitHub. Soubor pak můžete upravit pro svůj scénář.

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

Přidání definičního souboru rozhraní API do úložiště

Otestujte pracovní postup přidáním definičního souboru rozhraní API do úložiště. Postupujte podle těchto kroků vysoké úrovně, které jsou typické pro pracovní postup vývoje. Podrobnosti o práci s větvemi GitHubu najdete v dokumentaci k GitHubu.

Vytvořte novou pracovní větev z hlavní větve v úložišti.
Do úložiště APIs v cestě přidejte definiční soubor rozhraní API. Například APIs/catfacts-api/07-15-2024.json.
Potvrďte změny a nasdílejte je do pracovní větve.
Vytvořte žádost o přijetí změn pro sloučení pracovní větve do hlavní větve.
Po kontrole sloučíte žádost o přijetí změn. Sloučení aktivuje pracovní postup GitHub Actions, který zaregistruje rozhraní API v centru rozhraní API.

Ověření registrace rozhraní API

Ověřte, že je rozhraní API zaregistrované ve vašem centru rozhraní API.

Na webu Azure Portal přejděte do centra rozhraní API.
V nabídce vlevo v části Prostředky vyberte rozhraní API.
Ověřte, že se nově zaregistrované rozhraní API zobrazí v seznamu rozhraní API.

Snímek obrazovky s rozhraním API zaregistrovaným ve službě API Center po pracovním postupu

Přidání nové verze rozhraní API

Pokud chcete přidat novou verzi do existujícího rozhraní API ve vašem centru rozhraní API, postupujte podle předchozích kroků s mírnou úpravou:

Přejděte na stejnou pracovní větev v úložišti nebo vytvořte novou pracovní větev.
Do úložiště v APIs cestě přidejte nový definiční soubor rozhraní API ve složce pro existující rozhraní API. Pokud jste například dříve přidali definici rozhraní CAT Fakta API, přidejte novou verzi, například APIs/catfacts-api/07-22-2024.json.
Potvrďte změny a nasdílejte je do pracovní větve.
Vytvořte žádost o přijetí změn pro sloučení pracovní větve do hlavní větve.
Po kontrole sloučíte žádost o přijetí změn. Sloučení aktivuje pracovní postup GitHub Actions, který zaregistruje novou verzi rozhraní API v centru rozhraní API.
Na webu Azure Portal přejděte do centra rozhraní API a ověřte, že je nová verze zaregistrovaná.

Rozšíření scénáře

Pracovní postup GitHub Actions můžete rozšířit tak, aby zahrnoval další kroky, například přidání metadat pro registraci rozhraní API. Příklad:

Pomocí schématu metadat ve vašem centru rozhraní API vytvořte soubor JSON metadat, který použije hodnoty metadat pro vaši registraci rozhraní API.

Pokud například schéma metadat obsahuje vlastnosti, jako approverteamje například , a cost centersoubor JSON metadat může vypadat takto:
```
{
  "approver": "diego@contoso.com",
  "team": "Store API dev team",
  "costCenter": "12345"  
}
```
Nahrajte soubor JSON metadat ve složce pro každé rozhraní API v úložišti.
Přidejte krok pracovního postupu pro použití metadat pro registraci rozhraní API pomocí příkazu az apic api update . V následujícím příkladu se ID rozhraní API a soubor metadat předávají v proměnných prostředí, které by se nastavily jinde v souboru pracovního postupu.
```
[...]
- 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 }}
```

Sdílet prostřednictvím

Registrace rozhraní API v centru rozhraní API pomocí GitHub Actions

Požadavky

Nastavení pracovního postupu GitHub Actions

Nastavení tajného kódu instančního objektu

Přidání instančního objektu jako tajného kódu GitHubu

Přidání souboru pracovního postupu do úložiště GitHub

Přidání definičního souboru rozhraní API do úložiště

Ověření registrace rozhraní API

Přidání nové verze rozhraní API

Rozšíření scénáře

Váš názor

Další materiály

Sdílet prostřednictvím

Registrace rozhraní API v centru rozhraní API pomocí GitHub Actions

Požadavky

Nastavení pracovního postupu GitHub Actions

Nastavení tajného kódu instančního objektu

Přidání instančního objektu jako tajného kódu GitHubu

Přidání souboru pracovního postupu do úložiště GitHub

Přidání definičního souboru rozhraní API do úložiště

Ověření registrace rozhraní API

Přidání nové verze rozhraní API

Rozšíření scénáře

Související obsah

Váš názor

Další materiály