Registrar APIs em seu centro de API usando o GitHub Actions

Artigo
07/31/2024

Este artigo mostra como configurar um fluxo de trabalho básico do GitHub Actions para registrar uma API no centro de API da sua organização quando um arquivo de especificação de API é adicionado a um repositório GitHub.

Usar um fluxo de trabalho do GitHub Actions para registrar APIs em seu centro de API fornece um processo de CI/CD consistente e repetível para cada API nova ou atualizada. O fluxo de trabalho pode ser estendido para incluir etapas como adicionar metadados ao registro de API.

O diagrama a seguir mostra como o registro de API em seu centro de API pode ser automatizado usando um fluxo de trabalho do GitHub Actions.

Configure um fluxo de trabalho do GitHub Actions em seu repositório que é disparado quando uma solicitação de pull que adiciona um arquivo de definição de API é mesclada.
Crie um branch a partir do branch principal em seu repositório GitHub.
Adicione um arquivo de definição de API, confirme as alterações e envie-as por push para o novo branch.
Crie uma solicitação de pull para mesclar o novo branch no branch principal.
Mesclar a solicitação de pull.
A mesclagem dispara um fluxo de trabalho do GitHub Actions que registra a API no centro de API.

Pré-requisitos

Um centro de API na sua assinatura do Azure. Se você ainda não criou um, consulte Início Rápido: criar seu centro de API.
Permissões para criar uma entidade de serviço no locatário da ID do Microsoft Entra
Uma conta do GitHub e um repositório GitHub no qual você pode configurar segredos e fluxos de trabalho do GitHub Actions
Para a CLI do Azure:
- Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
- Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
  - Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
  - Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
  - Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.
Observação

Os comandos az apic exigem a extensão da CLI do Azure apic-extension. Se você não tiver usado comandos az apic, a extensão poderá ser instalada dinamicamente quando você executar seu primeiro comando az apic ou instalar a extensão manualmente. Saiba mais sobre as extensões da CLI do Azure.

Confira as notas sobre a versão para ver as últimas alterações e atualizações no apic-extension.

Observação

Os exemplos de comando da CLI do Azure incluídos neste artigo podem ser executados no PowerShell ou em um shell do Bash. Sempre que necessário, devido às diferentes sintaxes variáveis, são fornecidos exemplos de comando separados para os dois shells.

Configurar um fluxo de trabalho do GitHub Actions

Nesta seção, você configurará o fluxo de trabalho do GitHub Actions para este cenário:

Crie uma entidade de serviço para usar para credenciais do Azure no fluxo de trabalho.
Adicione as credenciais como um segredo em seu repositório GitHub.
Configure um fluxo de trabalho do GitHub Actions que é disparado quando uma solicitação de pull que adiciona um arquivo de definição de API é mesclada. O arquivo YAML de fluxo de trabalho inclui uma etapa que usa a CLI do Azure para registrar a API no centro de API do arquivo de definição.

Configurar um segredo da entidade de serviço

Nas etapas a seguir, crie uma entidade de serviço do Microsoft Entra ID, que será usada para adicionar credenciais ao fluxo de trabalho para autenticar com o Azure.

Observação

A configuração de uma entidade de serviço é mostrada para fins de demonstração. A maneira recomendada de autenticar com o Azure para GitHub Actions é com o OpenID Connect, um método de autenticação que usa tokens de curta duração. Configurar o OpenID Connect com o GitHub Actions é mais complexo, mas oferece segurança reforçada. Saiba mais

Crie uma entidade de serviço usando o comando az ad sp create-for-rbac. O exemplo a seguir usa primeiro o comando az apic show para recuperar a ID do recurso do centro de API. Em seguida, a entidade de serviço é criada com a função colaborador do Serviço do Centro de API do Azure para o centro de 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

Copie a saída JSON, que deve ser semelhante à seguinte:

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

Adicionar a entidade de serviço como um segredo do GitHub

Em GitHub, procure seu repositório. Selecione Configurações.
Em Segurança, selecione Segredos e variáveis>Ações
Selecione Novo segredo de repositório.
Cole toda a saída JSON do comando da CLI do Azure no campo valor do segredo. Nomeie o segredo como AZURE_CREDENTIALS. Selecione Adicionar segredo.

O segredo está listado em Segredos do repositório.

Quando você configurar o arquivo de fluxo de trabalho do GitHub posteriormente, use o segredo para a entrada creds da ação Azure/login. Por exemplo:

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

Adicionar o arquivo de fluxo de trabalho ao seu repositório GitHub

Um fluxo de trabalho do GitHub Actions é representado por um arquivo de definição YAML (.yml). Essa definição contém as várias etapas e os parâmetros que compõem o fluxo de trabalho. Saiba mais

Veja a seguir um arquivo de fluxo de trabalho básico para este exemplo que você pode usar ou modificar.

Neste exemplo:

O fluxo de trabalho é disparado quando uma solicitação de pull que adiciona uma definição JSON no caminho APIs é fechada no branch principal.
O local da definição é extraído da solicitação de pull usando um script do GitHub, que é autenticado com o token GitHub padrão.
As credenciais do Azure salvas em seu repositório são usadas para entrar no Azure.
O comando az apic register registra a API no centro de API especificado nas variáveis de ambiente.

Para configurar o arquivo de fluxo de trabalho:

Copie e salve o arquivo em um nome como register-api.yml.
Atualize os valores das variáveis de ambiente para corresponder ao centro de API no Azure.
Confirme ou atualize o nome da pasta do repositório (APIs) em que você adicionará o arquivo de definição de API.
Adicione esse arquivo de fluxo de trabalho no caminho /.github/workflows/ no repositório GitHub.

Dica

Usando a extensão Visual Studio Code para o Centro de API do Azure, você pode gerar um arquivo de fluxo de trabalho inicial executando um comando de extensão. Na Paleta de Comandos, selecione Centro de API do Azure: Registrar APIs. Selecione CI/CD>GitHub. Em seguida, você pode modificar o arquivo para seu cenário.

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

Adicionar o arquivo de definição de API ao repositório

Teste o fluxo de trabalho adicionando um arquivo de definição de API ao repositório. Siga estas etapas de alto nível, que são típicas de um fluxo de trabalho de desenvolvimento. Para obter detalhes sobre como trabalhar com branches do GitHub, consulte a documentação do GitHub.

Crie uma nova ramificação de trabalho do branch principal em seu repositório.
Adicione o arquivo de definição de API ao repositório no caminho APIs. Por exemplo, APIs/catfacts-api/07-15-2024.json.
Confirme as alterações e envie-as por push para o branch de trabalho.
Crie uma solicitação de pull para mesclar o branch de trabalho no branch principal.
Após a revisão, mescle a solicitação de pull. A mesclagem dispara o fluxo de trabalho do GitHub Actions que registra a API no centro de API.

Verificar o registro de API

Verifique se a API está registrada no centro de API.

No portal do Azure, navegue até o centro de API.
No menu à esquerda, em Ativos, selecione APIs.
Verifique se a API recém-registrada aparece na lista de APIs.

Captura de tela da API registrada no Centro de API após o fluxo de trabalho.

Adicionar uma nova versão da API

Para adicionar uma nova versão a uma API existente no centro de API, siga as etapas anteriores, com uma pequena modificação:

Altere para o mesmo branch de trabalho em seu repositório ou crie uma nova ramificação de trabalho.
Adicione um novo arquivo de definição de API ao repositório no caminho APIs, na pasta de uma API existente. Por exemplo, se você adicionou anteriormente uma definição de API de Fatos de Gato, adicione uma nova versão, como APIs/catfacts-api/07-22-2024.json.
Confirme as alterações e envie-as por push para o branch de trabalho.
Crie uma solicitação de pull para mesclar o branch de trabalho no branch principal.
Após a revisão, mescle a solicitação de pull. A mesclagem dispara o fluxo de trabalho do GitHub Actions que registra a nova versão da API no centro de API.
No portal do Azure, navegue até o centro de API e confirme se a nova versão está registrada.

Estender o cenário

Você pode estender o fluxo de trabalho do GitHub Actions para incluir outras etapas, como adicionar metadados para o registro de API. Por exemplo:

Usando o esquema de metadados em seu centro de API, crie um arquivo JSON de metadados para aplicar valores de metadados ao registro de API.

Por exemplo, se o esquema de metadados incluir propriedades como approver, team e cost center, um arquivo JSON de metadados, poderá ter esta aparência:
```
{
  "approver": "diego@contoso.com",
  "team": "Store API dev team",
  "costCenter": "12345"  
}
```
Carregue um arquivo JSON de metadados na pasta para cada API no repositório.
Adicione uma etapa de fluxo de trabalho para aplicar os metadados ao registro de API usando o comando az apic api update. No exemplo a seguir, a ID da API e o arquivo de metadados são passados em variáveis de ambiente, que seriam definidas em outro lugar no arquivo de fluxo de trabalho.
```
[...]
- 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 }}
```

Compartilhar via

Registrar APIs em seu centro de API usando o GitHub Actions

Pré-requisitos

Configurar um fluxo de trabalho do GitHub Actions

Configurar um segredo da entidade de serviço

Adicionar a entidade de serviço como um segredo do GitHub

Adicionar o arquivo de fluxo de trabalho ao seu repositório GitHub

Adicionar o arquivo de definição de API ao repositório

Verificar o registro de API

Adicionar uma nova versão da API

Estender o cenário

Comentários

Recursos adicionais

Compartilhar via

Registrar APIs em seu centro de API usando o GitHub Actions

Pré-requisitos

Configurar um fluxo de trabalho do GitHub Actions

Configurar um segredo da entidade de serviço

Adicionar a entidade de serviço como um segredo do GitHub

Adicionar o arquivo de fluxo de trabalho ao seu repositório GitHub

Adicionar o arquivo de definição de API ao repositório

Verificar o registro de API

Adicionar uma nova versão da API

Estender o cenário

Conteúdo relacionado

Comentários

Recursos adicionais