你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 GitHub Actions 在 API 中心注册 API

项目
07/26/2024

本文介绍如何在将 API 规范文件添加到 GitHub 存储库时设置基本的 GitHub Actions 工作流，以在组织的 API 中心注册 API。

使用 GitHub Actions 工作流在 API 中心注册 API 可为每个新的或更新后的 API 提供一致且可重复的 CI/CD 过程。可以扩展工作流，以包括将元数据添加到 API 注册等步骤。

下图显示了如何使用 GitHub Actions 工作流在 API 中心自动进行 API 注册。

在存储库中设置 GitHub Actions 工作流，该工作流会在合并添加 API 定义文件的拉取请求时触发。
根据 GitHub 存储库中的主分支创建分支。
添加 API 定义文件，提交更改，并将其推送到新分支。
创建拉取请求以将新分支合并到主分支中。
合并拉取请求。
该合并会触发在 API 中心注册 API 的 GitHub Actions 工作流。

先决条件

Azure 订阅中的 API 中心。如果尚未创建 API 中心，请参阅快速入门：创建 API 中心。
在 Microsoft Entra ID 租户中创建服务主体的权限
GitHub 帐户和 GitHub 存储库（可在其中配置机密和 GitHub Actions 工作流）
对于 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。
注意

az apic 命令需要 Azure CLI 扩展 apic-extension。如果尚未使用 az apic 命令，则可以在运行第一个 az apic 命令时动态安装扩展，也可以手动安装扩展。详细了解 Azure CLI 扩展。

请参阅最新更改的发行说明和 apic-extension 中的更新。

注意

本文中的 Azure CLI 命令示例可以在 PowerShell 或 bash shell 中运行。由于不同的变量语法，需要为两个 shell 提供单独的命令示例。

设置 GitHub Actions 工作流

在本部分中，你将设置适用于此方案的 GitHub Actions 工作流：

创建用于工作流中 Azure 凭据的服务主体。
将凭据添加为 GitHub 存储库中的机密。
配置会在合并添加 API 定义文件的拉取请求时触发的 GitHub Actions 工作流。工作流 YAML 文件包括了一个步骤，以使用 Azure CLI 从定义文件在 API 中心注册 API。

设置服务主体机密

以下步骤会创建一个Microsoft Entra ID 服务主体，用于向工作流添加凭据，以向 Azure 进行身份验证。

注意

所显示的配置服务主体仅供演示之用用。对于 GitHub Actions，向 Azure 进行身份验证的建议方法是使用 OpenID Connect，这是一种使用短期令牌的身份验证方法。使用 GitHub Actions 设置 OpenID Connect 更为复杂，但提供更强的安全性。了解详细信息

使用 az ad sp create-for-rbac 命令创建服务主体。以下示例首先使用 az apic show 命令检索了 API 中心的资源 ID。然后会为该 API 中心创建具有 Azure API 中心服务参与者角色的服务主体。

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

复制 JSON 输出，其外观应类似于以下内容：

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

将服务主体添加为 GitHub 机密

在 GitHub 中，浏览你的存储库。选择“设置”。
在“安全性”下，选择“机密和变量”>“操作”
选择“新建存储库机密”。
将 Azure CLI 命令的整个 JSON 输出粘贴到机密的值字段中。将机密命名为 AZURE_CREDENTIALS。选择“添加机密”。

机密列出在“存储库机密”下面。

以后配置 GitHub 工作流文件时，请使用该机密作为“Azure/登录”的输入 creds。例如：

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

将工作流文件添加到 GitHub 存储库

GitHub Actions 工作流由 YAML (.yml) 定义文件表示。此定义包含组成工作流的各种步骤和参数。了解详细信息

下面是适用于此示例的一个基本工作流文件，可以使用它或对其进行修改。

在此示例中：

当在主分支上关闭在 APIs 路径中添加 JSON 定义的拉取请求时，将会触发工作流。
定义的位置是从拉取请求中使用 GitHub 脚本提取的，该脚本使用默认的 GitHub 令牌进行身份验证。
存储库中保存的 Azure 凭据将用于登录到 Azure。
az apic register 命令可在环境变量中指定的 API 中心注册 API。

要配置工作流文件，请：

复制文件并将其保存在一个名称下，例如 register-api.yml。
更新环境变量的值以匹配 Azure 中的 API 中心。
确认或更新要在其中添加 API 定义文件的存储库文件夹（APIs）的名称。
在 GitHub 存储库的 /.github/workflows/ 路径中添加此工作流文件。

提示

使用适用于 Azure API 中心的 Visual Studio Code 扩展，可以通过运行扩展命令生成启动工作流文件。在命令面板中，选择“Azure API 中心：注册 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 文档。

根据存储库中的主分支创建新的工作分支。
将 API 定义文件添加到 APIs 路径中的存储库。例如 APIs/catfacts-api/07-15-2024.json。
提交更改并将其推送到工作分支。
创建拉取请求，以将工作分支合并到主分支中。
查看后，合并拉取请求。合并会触发在 API 中心注册 API 的 GitHub Actions 工作流。

验证 API 注册

验证 API 是否已在 API 中心注册。

在 Azure 门户中，导航到 API 中心。
在左侧菜单中“资产”下，选择“API”。
验证新注册的 API 是否显示在 API 列表中。

工作流后在 API 中心注册的 API 的屏幕截图。

添加新的 API 版本

要将新版本添加到 API 中心中的现有 API，请按照前面的步骤操作，且只需稍加修改：

更改为存储库中的同一工作分支，或创建新的工作分支。
将新的 API 定义文件添加到 APIs 路径中现有 API 的文件夹中的存储库。例如，如果以前添加了 Cat Facts API 定义，请添加新版本，例如 APIs/catfacts-api/07-22-2024.json。
提交更改并将其推送到工作分支。
创建拉取请求，以将工作分支合并到主分支中。
查看后，合并拉取请求。合并会触发 GitHub Actions 工作流，从而在 API 中心注册新的 API 版本。
在 Azure 门户中，导航到 API 中心并确认已注册新版本。

扩展方案

可以扩展 GitHub Actions 工作流以包含其他步骤，例如添加 API 注册的元数据。例如：

在 API 中心使用元数据架构，可创建元数据 JSON 文件以将元数据值应用于 API 注册。

例如，如果元数据架构包含 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 中心注册 API

先决条件

设置 GitHub Actions 工作流

设置服务主体机密

将服务主体添加为 GitHub 机密

将工作流文件添加到 GitHub 存储库

将 API 定义文件添加到存储库

验证 API 注册

添加新的 API 版本

扩展方案

反馈

其他资源

通过

使用 GitHub Actions 在 API 中心注册 API

先决条件

设置 GitHub Actions 工作流

设置服务主体机密

将服务主体添加为 GitHub 机密

将工作流文件添加到 GitHub 存储库

将 API 定义文件添加到存储库

验证 API 注册

添加新的 API 版本

扩展方案

相关内容

反馈

其他资源