GitHub Actions を使用して API Center に API を登録する

[アーティクル]
07/27/2024

この記事では、API 仕様ファイルが GitHub リポジトリに追加されたときに、組織の API Center に API を登録するための基本的な GitHub Actions ワークフローを設定する方法について説明します。

GitHub Actions ワークフローを使用して API を API Center に登録すると、新しい API または更新された API ごとに一貫性のある反復可能な CI/CD プロセスが提供されます。このワークフローを拡張して、API 登録にメタデータを追加するなどのステップを含めることができます。

次の図は、GitHub Actions ワークフローを使用して API Center への API 登録を自動化する方法を示しています。

API 定義ファイルを追加する pull request がマージされたときにトリガーされる GitHub Actions ワークフローをリポジトリに設定します。
GitHub リポジトリのメインブランチからブランチを作成します。
API 定義ファイルを追加し、変更をコミットして、新しいブランチにプッシュします。
pull request を作成して新しいブランチをメインブランチにマージします。
pull request をマージします。
マージによって、API Center に API を登録する GitHub Actions ワークフローがトリガーされます。

前提条件

Azure サブスクリプション内の API センター。まだ作成していない場合は、「クイックスタート: API センターを作成する」を参照してください。
Microsoft Entra ID テナントにサービスプリンシパルを作成するためのアクセス許可
シークレットと GitHub Actions ワークフローを構成できる GitHub アカウントと GitHub リポジトリ
Azure CLI の場合
- Azure Cloud Shell で Bash 環境を使用します。詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。
- CLI リファレンスコマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。
  - ローカルインストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。認証プロセスを完了するには、ターミナルに表示される手順に従います。その他のサインインオプションについては、Azure CLI でのサインインに関するページを参照してください。
  - 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。
  - az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。最新バージョンにアップグレードするには、az upgrade を実行します。
Note

az apic コマンドには、apic-extensionAzure CLI 拡張機能が必要です。 az apic コマンドを使用していない場合は、最初の az apic コマンドの実行時に拡張機能を動的にインストールするか、拡張機能を手動でインストールできます。 Azure CLI 拡張機能の詳細については、こちらを参照してください。

apic-extension の最新の変更と更新については、リリースノートを参照してください。

Note

この記事の Azure CLI コマンドの例は、PowerShell または bash シェルで実行できます。変数の構文が異なるために必要な場合は、2 つのシェルで個別のコマンド例が提供されています。

GitHub Actions ワークフローを設定する

このセクションでは、このシナリオ用に GitHub Actions ワークフローを設定します。

ワークフローで Azure 資格情報に使用するサービスプリンシパルを作成します。
資格情報をシークレットとして GitHub リポジトリに追加します。
API 定義ファイルを追加する pull request がマージされたときにトリガーされる GitHub Actions ワークフローを構成します。ワークフロー YAML ファイルには、Azure CLI を使用して定義ファイルから API Center に API を登録するステップが含まれています。

サービスプリンシパルシークレットを設定する

次のステップでは、Microsoft Entra ID サービスプリンシパルを作成します。これは、Azure で認証するためのワークフローに資格情報を追加するために使用されます。

Note

サービスプリンシパルの構成は、デモの目的で示されています。 Azure で GitHub Actions を認証するための推奨方法は、有効期間の短いトークンを使用する認証方法である OpenID Connect を使用することです。 GitHub Actions を使用して OpenID Connect を設定する場合、より複雑な作業になりますが、セキュリティが強化されます。詳細情報

az ad sp create-for-rbac コマンドを使用して、サービスプリンシパルを作成します。次の例では、最初に az apic show コマンドを使用して、API Center のリソース ID を取得します。その後、API Center の投稿者ロールを使用してサービスプリンシパルが作成されます。

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 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 Contributor --scopes $apicResourceId --json-auth

次のような JSON 出力をコピーします。

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

サービスプリンシパルを GitHub シークレットとして追加します

GitHub でリポジトリを参照します。設定を選択します。
[セキュリティ] で、[シークレットと変数]>[アクション] を選択します
[New repository secret](新しいリポジトリシークレット) を選択します。
Azure CLI コマンドからの JSON 出力全体をシークレットの値フィールドに貼り付けます。シークレットに AZURE_CREDENTIALS という名前を付けます。 [Add secret](シークレットの追加) を選択します。

シークレットが [リポジトリシークレット] の下に一覧表示されます。

後で GitHub ワークフローファイルを構成するときに、Azure/login アクションの入力 creds にシークレットを使用します。次に例を示します。

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

GitHub リポジトリにワークフローファイルを追加する

GitHub Actions ワークフローは、YAML (.yml) 定義ファイルによって表されます。この定義には、ワークフローを構成するさまざまな手順とパラメーターが含まれます。詳細情報

以下は、この例に使用または変更できる基本的なワークフローファイルです。

次の点に注意してください。

APIs パスに JSON 定義を追加する pull request がメインブランチで閉じられると、ワークフローがトリガーされます。
定義の場所は、既定の GitHub トークンで認証される GitHub スクリプトを使用して pull request から抽出されます。
リポジトリに保存されている Azure 資格情報は、Azure へのサインインに使用されます。
az apic register コマンドは、環境変数で指定された API Center に API を登録します。

ワークフローファイルを構成するには:

ファイルをコピーして、register-api.yml などの名前で保存します。
Azure の API Center と一致するように環境変数の値を更新します。
API 定義ファイルを追加するリポジトリフォルダー (APIs) の名前を確認または更新します。
このワークフローファイルを GitHub リポジトリの /.github/workflows/ パスに追加します。

ヒント

Azure API Center の Visual Studio Code 拡張機能を使用すると、拡張機能コマンドを実行して開始ワークフローファイルを生成できます。コマンドパレットで、[Azure API Center: API の登録] を選択します。 [CI/CD]>[GitHub] を選択します。その後、実際のシナリオに合わせてファイルを変更できます。

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 定義ファイルを追加する

リポジトリに API 定義ファイルを追加して、ワークフローをテストします。次の大まかなステップに従います。これは開発ワークフローの一般的なステップです。 GitHub ブランチの操作の詳細については、GitHub のドキュメントを参照してください。

リポジトリのメインブランチから新しい作業ブランチを作成します。
APIs パスのリポジトリに API 定義ファイルを追加します。たとえば、APIs/catfacts-api/07-15-2024.json のようにします。
変更をコミットし、作業ブランチにそれらをプッシュします。
pull request を作成して作業ブランチをメインブランチにマージします。
確認後、pull request をマージします。マージによって、API Center に API を登録する GitHub Actions ワークフローがトリガーされます。

API 登録を確認する

API が API Center に登録されていることを確認します。

Azure portal で、API センターに移動します。
左側のメニューにある [資産] で、[API] を選択します。
新しく登録された API が API の一覧に表示されることを確認します。

ワークフロー後に API Center に登録された API のスクリーンショット。

新しい API バージョンを追加する

API Center の既存の API に新しいバージョンを追加するには、少し変更を加えて、前のステップに従います。

リポジトリ内の同じ作業ブランチに変更するか、新しい作業ブランチを作成します。
既存の API のフォルダー内の APIs パスのリポジトリに、新しい API 定義ファイルを追加します。たとえば、以前に Cat Facts API 定義を追加した場合は、APIs/catfacts-api/07-22-2024.json などの新しいバージョンを追加します。
変更をコミットし、作業ブランチにそれらをプッシュします。
pull request を作成して作業ブランチをメインブランチにマージします。
確認後、pull request をマージします。マージにより、新しい API バージョンを API Center に登録する GitHub Actions ワークフローがトリガーされます。
Azure portal で API Center に移動し、新しいバージョンが登録されていることを確認します。

シナリオを拡張する

GitHub Actions ワークフローを拡張して、API 登録のメタデータの追加など、他のステップを含めることができます。次に例を示します。

API Center でメタデータスキーマを使用して、API 登録にメタデータ値を適用するメタデータ JSON ファイルを作成します。

たとえば、メタデータスキーマに approver、team、cost center などのプロパティが含まれている場合、メタデータ JSON ファイルは次のようになります。
```
{
  "approver": "diego@contoso.com",
  "team": "Store API dev team",
  "costCenter": "12345"  
}
```
リポジトリ内の各 API のフォルダーにメタデータ JSON ファイルをアップロードします。
az apic api update コマンドを使用して、メタデータを API 登録に適用するワークフローステップを追加します。次の例では、API ID とメタデータファイルが環境変数で渡されます。環境変数は、ワークフローファイル内の別の場所で設定されます。
```
[...]
- 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 }}
```

次の方法で共有

GitHub Actions を使用して API Center に API を登録する

前提条件

GitHub Actions ワークフローを設定する

サービスプリンシパルシークレットを設定する

サービスプリンシパルを GitHub シークレットとして追加します

GitHub リポジトリにワークフローファイルを追加する

リポジトリに API 定義ファイルを追加する

API 登録を確認する

新しい API バージョンを追加する

シナリオを拡張する

フィードバック

その他のリソース

次の方法で共有

GitHub Actions を使用して API Center に API を登録する

前提条件

GitHub Actions ワークフローを設定する

サービス プリンシパル シークレットを設定する

サービス プリンシパルを GitHub シークレットとして追加します

GitHub リポジトリにワークフロー ファイルを追加する

リポジトリに API 定義ファイルを追加する

API 登録を確認する

新しい API バージョンを追加する

シナリオを拡張する

関連するコンテンツ

フィードバック

その他のリソース

サービスプリンシパルシークレットを設定する

サービスプリンシパルを GitHub シークレットとして追加します

GitHub リポジトリにワークフローファイルを追加する