Регистрация API в центре API с помощью GitHub Actions

Статья
12/23/2024

В этой статье показано, как настроить базовый рабочий процесс GitHub Actions для регистрации API в центре API организации при добавлении файла спецификации API в репозиторий GitHub.

Использование рабочего процесса GitHub Actions для регистрации API в центре API обеспечивает согласованный и повторяющийся процесс CI/CD для каждого нового или обновленного API. Рабочий процесс можно расширить, чтобы включить такие действия, как добавление метаданных в регистрацию API.

На следующей схеме показано, как регистрация API в центре API может быть автоматизирована с помощью рабочего процесса GitHub Actions.

Настройте рабочий процесс GitHub Actions в репозитории, который активируется при добавлении файла определения API при добавлении запроса на вытягивание.
Создайте ветвь из основной ветви в репозитории GitHub.
Добавьте файл определения API, зафиксируйте изменения и отправьте его в новую ветвь.
Создайте запрос на вытягивание, чтобы объединить новую ветвь в основную ветвь.
Слияние запроса на вытягивание.
Слияние активирует рабочий процесс GitHub Actions, который регистрирует API в центре API.

Необходимые компоненты

Центр API в подписке Azure. Если вы еще не создали его, см . краткое руководство. Создание центра API.
Разрешения на создание субъекта-службы в клиенте Идентификатора Microsoft Entra
Учетная запись GitHub и репозиторий GitHub, в котором можно настроить секреты и рабочие процессы GitHub Actions
При использовании Azure CLI выполните следующее:
- Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure Cloud Shell.
- Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.
  - Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью Azure CLI.
  - Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.
  - Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.
Примечание.

az apic для команд требуется apic-extension расширение Azure CLI. Если вы не использовали az apic команды, расширение можно установить динамически при выполнении первой az apic команды или установить расширение вручную. Дополнительные сведения о расширениях Azure CLI.

Дополнительные сведения о последних изменениях и обновлениях см. в заметках о выпускеapic-extension. Для некоторых функций может потребоваться предварительная версия или определенная версия расширения.

Примечание.

Примеры команд Azure CLI в этой статье могут выполняться в PowerShell или оболочке bash. Если это необходимо из-за разного синтаксиса переменной, для двух оболочк предоставляются отдельные примеры команд.

Настройка рабочего процесса GitHub Actions

В этом разделе описана настройка рабочего процесса GitHub Actions для этого сценария:

Создайте субъект-службу для использования учетных данных Azure в рабочем процессе.
Добавьте учетные данные в качестве секрета в репозитории GitHub.
Настройте рабочий процесс GitHub Actions, который активируется при добавлении файла определения API при добавлении запроса на вытягивание. Файл YAML рабочего процесса включает шаг, который использует Azure CLI для регистрации API в центре API из файла определения.

Настройка секрета субъекта-службы

На следующих шагах создайте субъект-службу идентификатора Microsoft Entra ID, который будет использоваться для добавления учетных данных в рабочий процесс для проверки подлинности в Azure.

Примечание.

Настройка субъекта-службы показана для демонстрационных целей. Рекомендуемый способ проверки подлинности с помощью Azure for GitHub Actions — с помощью OpenID Connect, метода проверки подлинности, использующего короткие маркеры. Настройка OpenID Connect с помощью GitHub Actions более сложна, но обеспечивает защищенное обеспечение безопасности. Подробнее

Создайте субъект-службу с помощью команды az ad sp create-for-rbac. В следующем примере сначала используется команда az apic show для получения идентификатора ресурса центра API. Затем субъект-служба создается с ролью участника службы Центра 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 найдите нужный репозиторий. Выберите Параметры.
В разделе "Безопасность" выберите "Секреты и переменные>"
Нажмите Создать секрет репозитория.
Вставьте все выходные данные JSON, полученные из команды Azure CLI, в поле значения секрета. Присвойте этому секрету имя AZURE_CREDENTIALS. Выберите Добавить секрет.

Секрет указан в разделе секретов репозитория.

При настройке файла рабочего процесса GitHub позже вы используете секрет для ввода creds действия azure/login . Например:

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

Добавление файла рабочего процесса в репозиторий GitHub

Рабочий процесс GitHub Actions представлен файлом определения YAML (.yml). Это определение содержит разные шаги и параметры рабочего процесса. Подробнее

Ниже приведен базовый файл рабочего процесса для этого примера, который можно использовать или изменить.

В этом примере:

Рабочий процесс активируется, когда запрос на вытягивание, добавляющий определение JSON в APIs путь, закрывается в главной ветви.
Расположение определения извлекается из запроса на вытягивание с помощью скрипта GitHub, который проходит проверку подлинности с помощью маркера GitHub по умолчанию.
Учетные данные Azure, сохраненные в репозитории, используются для входа в Azure.
Команда az apic register регистрирует API в центре API, указанном в переменных среды.

Чтобы настроить файл рабочего процесса, выполните следующие действия.

Скопируйте и сохраните файл под именем, например register-api.yml.
Подтвердите или обновите имя папки репозитория (APIs), где вы добавите файл определения API.
Добавьте этот файл рабочего процесса в путь к /.github/workflows/ репозиторию GitHub.
Задайте переменные SERVICE_NAME Actions и RESOURCE_GROUP в репозитории для имени центра API и имени группы ресурсов в Azure.

Совет

С помощью расширения Visual Studio Code для Центра API Azure можно создать начальный файл рабочего процесса, выполнив команду расширения. В палитре команд выберите Центр API Azure: регистрация 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
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 в репозиторий

Протестируйте рабочий процесс, добавив файл определения API в репозиторий. Выполните эти высокоуровневые действия, которые являются типичными для рабочего процесса разработки. Дополнительные сведения о работе с филиалами GitHub см. в документации по GitHub.

Создайте рабочую ветвь из основной ветви в репозитории.
Добавьте файл определения API в репозиторий в APIs пути. Например, APIs/catfacts-api/07-15-2024.json.
Зафиксируйте изменения и отправьте их в рабочую ветвь.
Создайте запрос на вытягивание, чтобы объединить рабочую ветвь в основную ветвь.
После проверки выполните слияние запроса на вытягивание. Слияние активирует рабочий процесс GitHub Actions, который регистрирует API в центре API.

Проверка регистрации API

Убедитесь, что API зарегистрирован в центре API.

В портал Azure перейдите в центр API.
В меню слева в разделе "Активы" выберите API.
Убедитесь, что только что зарегистрированный API отображается в списке API.

Снимок экрана: API, зарегистрированный в Центре API после рабочего процесса.

Добавление новой версии API

Чтобы добавить новую версию в существующий API в центре API, выполните описанные выше действия с небольшим изменением:

Измените ту же рабочую ветвь в репозитории или создайте новую рабочую ветвь.
Добавьте новый файл определения API в репозиторий в APIs папке для существующего API. Например, если вы ранее добавили определение API Cat Facts, добавьте новую версию, например APIs/catfacts-api/07-22-2024.json.
Зафиксируйте изменения и отправьте их в рабочую ветвь.
Создайте запрос на вытягивание, чтобы объединить рабочую ветвь в основную ветвь.
После проверки выполните слияние запроса на вытягивание. Слияние активирует рабочий процесс GitHub Actions, который регистрирует новую версию API в центре API.
В портал Azure перейдите в центр API и убедитесь, что новая версия зарегистрирована.

Расширение сценария

Вы можете расширить рабочий процесс GitHub Actions, чтобы включить другие шаги, например добавление метаданных для регистрации API. Например:

Используя схему метаданных в центре API, создайте JSON-файл метаданных для применения значений метаданных к регистрации API.

Например, если схема метаданных содержит такие свойства, как approver, teamи cost centerjson-файл метаданных может выглядеть следующим образом:
```
{
  "approver": "diego@contoso.com",
  "team": "Store API dev team",
  "costCenter": "12345"  
}
```
Отправьте JSON-файл метаданных в папку для каждого API в репозитории.
Добавьте шаг рабочего процесса, чтобы применить метаданные к регистрации API с помощью команды az apic api update . В следующем примере идентификатор API и файл метаданных передаются в переменные среды, которые будут заданы в другом месте файла рабочего процесса.
```
[...]
- 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 }}
```

Поделиться через

Регистрация API в центре API с помощью GitHub Actions

Необходимые компоненты

Настройка рабочего процесса GitHub Actions

Настройка секрета субъекта-службы

Добавление субъекта-службы в качестве секрета GitHub

Добавление файла рабочего процесса в репозиторий GitHub

Добавление файла определения API в репозиторий

Проверка регистрации API

Добавление новой версии API

Расширение сценария

Обратная связь

Дополнительные ресурсы

Поделиться через

Регистрация API в центре API с помощью GitHub Actions

Необходимые компоненты

Настройка рабочего процесса GitHub Actions

Настройка секрета субъекта-службы

Добавление субъекта-службы в качестве секрета GitHub

Добавление файла рабочего процесса в репозиторий GitHub

Добавление файла определения API в репозиторий

Проверка регистрации API

Добавление новой версии API

Расширение сценария

Связанный контент

Обратная связь

Дополнительные ресурсы