Rejestrowanie interfejsów API w centrum interfejsu API przy użyciu funkcji GitHub Actions

Artykuł
07/25/2024

W tym artykule pokazano, jak skonfigurować podstawowy przepływ pracy funkcji GitHub Actions w celu zarejestrowania interfejsu API w centrum interfejsu API organizacji po dodaniu pliku specyfikacji interfejsu API do repozytorium GitHub.

Używanie przepływu pracy funkcji GitHub Actions do rejestrowania interfejsów API w centrum interfejsu API zapewnia spójny i powtarzalny proces ciągłej integracji/ciągłego wdrażania dla każdego nowego lub zaktualizowanego interfejsu API. Przepływ pracy można rozszerzyć, aby uwzględnić kroki, takie jak dodawanie metadanych do rejestracji interfejsu API.

Na poniższym diagramie pokazano, jak można zautomatyzować rejestrację interfejsu API w centrum interfejsu API przy użyciu przepływu pracy funkcji GitHub Actions.

Skonfiguruj przepływ pracy funkcji GitHub Actions w repozytorium, który jest wyzwalany po scaleniu żądania ściągnięcia, które dodaje plik definicji interfejsu API.
Utwórz gałąź z gałęzi głównej w repozytorium GitHub.
Dodaj plik definicji interfejsu API, zatwierdź zmiany i wypchnij je do nowej gałęzi.
Utwórz żądanie ściągnięcia, aby scalić nową gałąź z gałęzią główną.
Scal żądanie ściągnięcia.
Scalanie wyzwala przepływ pracy funkcji GitHub Actions, który rejestruje interfejs API w centrum interfejsu API.

Wymagania wstępne

Centrum interfejsu API w ramach subskrypcji platformy Azure. Jeśli jeszcze go nie utworzono, zobacz Szybki start: tworzenie centrum interfejsu API.
Uprawnienia do tworzenia jednostki usługi w dzierżawie microsoft Entra ID
Konto usługi GitHub i repozytorium GitHub, w którym można skonfigurować wpisy tajne i przepływy pracy funkcji GitHub Actions
W przypadku interfejsu wiersza polecenia platformy Azure:
- Użyj środowiska powłoki Bash w usłudze Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Szybki start dotyczący powłoki Bash w usłudze Azure Cloud Shell.
- Jeśli wolisz uruchamiać polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj interfejs wiersza polecenia platformy Azure. Jeśli korzystasz z systemu Windows lub macOS, rozważ uruchomienie interfejsu wiersza polecenia platformy Azure w kontenerze Docker. Aby uzyskać więcej informacji, zobacz Jak uruchomić interfejs wiersza polecenia platformy Azure w kontenerze platformy Docker.
  - Jeśli korzystasz z instalacji lokalnej, zaloguj się do interfejsu wiersza polecenia platformy Azure za pomocą polecenia az login. Aby ukończyć proces uwierzytelniania, wykonaj kroki wyświetlane w terminalu. Aby uzyskać inne opcje logowania, zobacz Logowanie się przy użyciu interfejsu wiersza polecenia platformy Azure.
  - Po wyświetleniu monitu zainstaluj rozszerzenie interfejsu wiersza polecenia platformy Azure podczas pierwszego użycia. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Korzystanie z rozszerzeń w interfejsie wiersza polecenia platformy Azure.
  - Uruchom polecenie az version, aby znaleźć zainstalowane wersje i biblioteki zależne. Aby uaktualnić do najnowszej wersji, uruchom polecenie az upgrade.
Uwaga

az apic Polecenia wymagają rozszerzenia interfejsu wiersza polecenia platformy apic-extension Azure. Jeśli nie użyto az apic poleceń, rozszerzenie można zainstalować dynamicznie po uruchomieniu pierwszego az apic polecenia lub zainstalować rozszerzenie ręcznie. Dowiedz się więcej o rozszerzeniach interfejsu wiersza polecenia platformy Azure.

Zapoznaj się z informacjami o wersji, aby uzyskać najnowsze zmiany i aktualizacje w pliku apic-extension.

Uwaga

Przykłady poleceń interfejsu wiersza polecenia platformy Azure w tym artykule mogą być uruchamiane w programie PowerShell lub powłoce bash. W razie potrzeby ze względu na różne składnie zmiennych podano oddzielne przykłady poleceń dla dwóch powłok.

Konfigurowanie przepływu pracy funkcji GitHub Actions

W tej sekcji skonfigurujesz przepływ pracy funkcji GitHub Actions dla tego scenariusza:

Utwórz jednostkę usługi do użycia dla poświadczeń platformy Azure w przepływie pracy.
Dodaj poświadczenia jako wpis tajny w repozytorium GitHub.
Skonfiguruj przepływ pracy funkcji GitHub Actions, który jest wyzwalany po scaleniu żądania ściągnięcia, które dodaje plik definicji interfejsu API. Plik YAML przepływu pracy zawiera krok, który używa interfejsu wiersza polecenia platformy Azure do zarejestrowania interfejsu API w centrum interfejsu API z pliku definicji.

Konfigurowanie wpisu tajnego jednostki usługi

W poniższych krokach utwórz jednostkę usługi Microsoft Entra ID, która będzie używana do dodawania poświadczeń do przepływu pracy w celu uwierzytelniania za pomocą platformy Azure.

Uwaga

Konfigurowanie jednostki usługi jest wyświetlane w celach demonstracyjnych. Zalecanym sposobem uwierzytelniania za pomocą funkcji Azure for GitHub Actions jest użycie narzędzia OpenID Connect, czyli metody uwierzytelniania, która używa tokenów krótkotrwałych. Konfigurowanie programu OpenID Connect za pomocą funkcji GitHub Actions jest bardziej złożone, ale oferuje zabezpieczenia ze wzmocnionymi zabezpieczeniami. Dowiedz się więcej

Utwórz jednostkę usługi za pomocą polecenia az ad sp create-for-rbac. W poniższym przykładzie najpierw użyto polecenia az apic show w celu pobrania identyfikatora zasobu centrum interfejsu API. Jednostka usługi jest następnie tworzona przy użyciu roli Współautor usługi Centrum interfejsu API platformy Azure dla centrum interfejsu API.

Bash
Program 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

Skopiuj dane wyjściowe JSON, które powinny wyglądać podobnie do następujących:

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

Dodawanie jednostki usługi jako wpisu tajnego usługi GitHub

W usłudze GitHub przejrzyj repozytorium. Wybierz Ustawienia.
W obszarze Zabezpieczenia wybierz pozycję Wpisy tajne i zmienne>Akcje
Wybierz pozycję Nowy wpis tajny repozytorium.
Wklej całe dane wyjściowe JSON z polecenia interfejsu wiersza polecenia platformy Azure do pola wartości wpisu tajnego. Nadaj kluczowi nazwę wpisu tajnego AZURE_CREDENTIALS. Wybierz przycisk Add secret (Dodaj wpis tajny).

Wpis tajny znajduje się w obszarze Wpisy tajne repozytorium.

Podczas późniejszego konfigurowania pliku przepływu pracy usługi GitHub należy użyć wpisu tajnego dla akcji Azurecreds/login. Na przykład:

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

Dodawanie pliku przepływu pracy do repozytorium GitHub

Przepływ pracy funkcji GitHub Actions jest reprezentowany przez plik definicji YAML (.yml). Ta definicja zawiera różne kroki i parametry tworzące przepływ pracy. Dowiedz się więcej

Poniżej przedstawiono podstawowy plik przepływu pracy dla tego przykładu, którego można użyć lub zmodyfikować.

W tym przykładzie:

Przepływ pracy jest wyzwalany, gdy żądanie ściągnięcia, które dodaje definicję JSON w APIs ścieżce, jest zamykane w gałęzi głównej.
Lokalizacja definicji jest wyodrębniana z żądania ściągnięcia przy użyciu skryptu usługi GitHub, który jest uwierzytelniany przy użyciu domyślnego tokenu usługi GitHub.
Poświadczenia platformy Azure zapisane w repozytorium są używane do logowania się na platformie Azure.
Polecenie az apic register rejestruje interfejs API w centrum interfejsu API określonym w zmiennych środowiskowych.

Aby skonfigurować plik przepływu pracy:

Skopiuj i zapisz plik pod nazwą, taką jak register-api.yml.
Zaktualizuj wartości zmiennych środowiskowych, aby odpowiadały centrum interfejsu API na platformie Azure.
Potwierdź lub zaktualizuj nazwę folderu repozytorium (APIs), w którym zostanie dodany plik definicji interfejsu API.
Dodaj ten plik przepływu pracy w ścieżce /.github/workflows/ w repozytorium GitHub.

Napiwek

Za pomocą rozszerzenia programu Visual Studio Code dla centrum interfejsu API platformy Azure możesz wygenerować początkowy plik przepływu pracy, uruchamiając polecenie rozszerzenia. W palecie poleceń wybierz pozycję Centrum interfejsów API platformy Azure: Zarejestruj interfejsy API. Wybierz pozycję Ciągła integracja/ciągłe wdrażanie>w usłudze GitHub. Następnie możesz zmodyfikować plik dla danego scenariusza.

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

Dodawanie pliku definicji interfejsu API do repozytorium

Przetestuj przepływ pracy, dodając plik definicji interfejsu API do repozytorium. Wykonaj te ogólne kroki, które są typowe dla przepływu pracy programowania. Aby uzyskać szczegółowe informacje na temat pracy z gałęziami usługi GitHub, zobacz dokumentację usługi GitHub.

Utwórz nową gałąź roboczą z gałęzi głównej w repozytorium.
Dodaj plik definicji interfejsu API do repozytorium w ścieżce APIs . Na przykład APIs/catfacts-api/07-15-2024.json.
Zatwierdź zmiany i wypchnij je do gałęzi roboczej.
Utwórz żądanie ściągnięcia, aby scalić gałąź roboczą z gałęzią główną.
Po przejrzeniu scal żądanie ściągnięcia. Scalanie wyzwala przepływ pracy funkcji GitHub Actions, który rejestruje interfejs API w centrum interfejsu API.

Weryfikowanie rejestracji interfejsu API

Sprawdź, czy interfejs API jest zarejestrowany w Centrum interfejsu API.

W witrynie Azure Portal przejdź do centrum interfejsu API.
W menu po lewej stronie w obszarze Zasoby wybierz pozycję Interfejsy API.
Sprawdź, czy nowo zarejestrowany interfejs API znajduje się na liście interfejsów API.

Zrzut ekranu przedstawiający interfejs API zarejestrowany w centrum interfejsu API po przepływie pracy.

Dodawanie nowej wersji interfejsu API

Aby dodać nową wersję do istniejącego interfejsu API w centrum interfejsu API, wykonaj poprzednie kroki z niewielkimi modyfikacjami:

Przejdź do tej samej gałęzi roboczej w repozytorium lub utwórz nową gałąź roboczą.
Dodaj nowy plik definicji interfejsu API do repozytorium w APIs ścieżce w folderze dla istniejącego interfejsu API. Jeśli na przykład wcześniej dodano definicję interfejsu API Cat Facts, dodaj nową wersję, taką jak APIs/catfacts-api/07-22-2024.json.
Zatwierdź zmiany i wypchnij je do gałęzi roboczej.
Utwórz żądanie ściągnięcia, aby scalić gałąź roboczą z gałęzią główną.
Po przejrzeniu scal żądanie ściągnięcia. Scalanie wyzwala przepływ pracy funkcji GitHub Actions, który rejestruje nową wersję interfejsu API w centrum interfejsu API.
W witrynie Azure Portal przejdź do centrum interfejsu API i upewnij się, że nowa wersja jest zarejestrowana.

Rozszerzanie scenariusza

Możesz rozszerzyć przepływ pracy funkcji GitHub Actions, aby uwzględnić inne kroki, takie jak dodawanie metadanych na potrzeby rejestracji interfejsu API. Na przykład:

Korzystając ze schematu metadanych w centrum interfejsu API, utwórz plik JSON metadanych, aby zastosować wartości metadanych do rejestracji interfejsu API.

Jeśli na przykład schemat metadanych zawiera właściwości, takie jak approver, teami cost center, plik JSON metadanych może wyglądać następująco:
```
{
  "approver": "diego@contoso.com",
  "team": "Store API dev team",
  "costCenter": "12345"  
}
```
Przekaż plik JSON metadanych w folderze dla każdego interfejsu API w repozytorium.
Dodaj krok przepływu pracy, aby zastosować metadane do rejestracji interfejsu API przy użyciu polecenia az apic api update . W poniższym przykładzie identyfikator interfejsu API i plik metadanych są przekazywane w zmiennych środowiskowych, które zostaną ustawione w innym miejscu w pliku przepływu pracy.
```
[...]
- 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 }}
```

Udostępnij za pośrednictwem

Rejestrowanie interfejsów API w centrum interfejsu API przy użyciu funkcji GitHub Actions

Wymagania wstępne

Konfigurowanie przepływu pracy funkcji GitHub Actions

Konfigurowanie wpisu tajnego jednostki usługi

Dodawanie jednostki usługi jako wpisu tajnego usługi GitHub

Dodawanie pliku przepływu pracy do repozytorium GitHub

Dodawanie pliku definicji interfejsu API do repozytorium

Weryfikowanie rejestracji interfejsu API

Dodawanie nowej wersji interfejsu API

Rozszerzanie scenariusza

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Rejestrowanie interfejsów API w centrum interfejsu API przy użyciu funkcji GitHub Actions

Wymagania wstępne

Konfigurowanie przepływu pracy funkcji GitHub Actions

Konfigurowanie wpisu tajnego jednostki usługi

Dodawanie jednostki usługi jako wpisu tajnego usługi GitHub

Dodawanie pliku przepływu pracy do repozytorium GitHub

Dodawanie pliku definicji interfejsu API do repozytorium

Weryfikowanie rejestracji interfejsu API

Dodawanie nowej wersji interfejsu API

Rozszerzanie scenariusza

Powiązana zawartość

Opinia

Dodatkowe zasoby