Регистрация API в вашем центре API с использованием GitHub Actions

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

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

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

Процесс включает следующие шаги.

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

Примечание.

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

Предварительные условия

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

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

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

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

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

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

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

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

Примечание.

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

Создайте учетную запись службы с помощью команды az ad sp create-for-rbac. В следующем примере сначала используется команда az apic show для получения идентификатора ресурса центра API. Затем учетная запись службы создается с ролью сотрудника службы Центра API Azure.

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.

В GitHub перейдите к репозиторию и выберите "Параметры " в верхней строке меню.
В левой панели навигации в разделе «Безопасность» выберите «Секреты и переменные»>, «Действия»
Нажмите Создать секрет репозитория.
В поле "Секрет" вставьте весь результат JSON из команды Azure CLI. В поле "Имя" введите AZURE_CREDENTIALS. Выберите Добавить секрет.

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

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

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

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

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

В следующем примере представлен базовый файл рабочего процесса, который можно использовать или изменить.

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

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

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

Совет

С помощью расширения Visual Studio Code для Центра API Azure можно создать начальный файл рабочего процесса, выполнив команду расширения. В палитре команд (CTRL+SHIFT+P) введите Центр 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.
Зафиксируйте изменения и отправьте их в рабочую ветвь.
Создайте pull request, чтобы объединить рабочую ветвь в основную ветвь.
После проверки выполните слияние пулл-реквеста. Слияние активирует рабочий процесс GitHub Actions, который регистрирует API в центре API.

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

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

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

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

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

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

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

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

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

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

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

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

Были ли сведения на этой странице полезными?

Last updated on 2026-02-26