Registre APIs em seu centro de APIs usando as Ações do GitHub
Este artigo mostra como configurar um fluxo de trabalho básico de Ações do GitHub 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 do GitHub.
O uso de um fluxo de trabalho de Ações do GitHub para registrar APIs em seu centro de APIs 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 a adição de metadados ao registro da API.
O diagrama a seguir mostra como o registro de API em seu centro de API pode ser automatizado usando um fluxo de trabalho de Ações do GitHub.
- Configure um fluxo de trabalho de Ações do GitHub em seu repositório que é acionado quando uma solicitação pull que adiciona um arquivo de definição de API é mesclada.
- Crie uma ramificação a partir da ramificação principal no repositório do GitHub.
- Adicione um arquivo de definição de API, confirme as alterações e envie-as para a nova ramificação.
- Crie uma solicitação pull para mesclar a nova ramificação na ramificação principal.
- Mescle a solicitação pull.
- A mesclagem aciona um fluxo de trabalho de Ações do GitHub que registra a API em sua central de APIs.
Pré-requisitos
Um centro de API na sua subscrição do Azure. Se você ainda não criou um, consulte Guia de início rápido: criar sua central de API.
Permissões para criar uma entidade de serviço no locatário do Microsoft Entra ID
Uma conta do GitHub e um repositório do GitHub no qual você pode configurar segredos e fluxos de trabalho de Ações do GitHub
Para a CLI do Azure:
Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.
Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.
Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.
Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.
Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.
Nota
az apiccomandos exigem a extensão da CLI doapic-extensionAzure. Se você não tiver usadoaz apiccomandos, a extensão pode ser instalada dinamicamente quando você executa seu primeiroaz apiccomando, ou você pode instalar a extensão manualmente. Saiba mais sobre as extensões da CLI do Azure.Consulte as notas de versão para obter as alterações e atualizações mais recentes no
apic-extension.Nota
Os exemplos de comandos da CLI do Azure neste artigo podem ser executados no PowerShell ou em um shell bash. Quando necessário devido à sintaxe variável diferente, exemplos de comandos separados são fornecidos para os dois shells.
Configurar um fluxo de trabalho de Ações do GitHub
Nesta seção, você configura o fluxo de trabalho Ações do GitHub 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 de Ações do GitHub que é acionado quando uma solicitação 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 em seu centro de API a partir 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.
Nota
A configuração de uma entidade de serviço é mostrada para fins de demonstração. A maneira recomendada de autenticar com o Azure for 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. Mais informações
Crie um principal de serviço com 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. A entidade de serviço é então criada com a função de Colaborador para o centro de API.
#! /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
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
No GitHub, navegue pelo repositório. Selecione Definições.
Em Segurança, selecione Segredos e variáveis>Ações
Selecione Novo segredo do repositório.
Cole toda a saída JSON do comando CLI do Azure no campo de valor do segredo. Nomeie o segredo
AZURE_CREDENTIALS. Selecione Add secret (Adicionar segredo).O segredo está listado em Segredos do repositório.
Ao configurar o arquivo de fluxo de trabalho do GitHub posteriormente, você usa o segredo para a entrada creds da ação Azure/login . Por exemplo:
- uses: azure/login@v1
with:
creds: ${{ secrets.AZURE_CREDENTIALS }}
Adicione o arquivo de fluxo de trabalho ao repositório GitHub
Um fluxo de trabalho de Ações do GitHub é representado por um arquivo de definição YAML (.yml). Esta definição contém as várias etapas e parâmetros que compõem o fluxo de trabalho. Mais informações
A seguir está um arquivo de fluxo de trabalho básico para este exemplo que você pode usar ou modificar.
Neste exemplo:
- O fluxo de trabalho é acionado quando uma solicitação pull que adiciona uma definição JSON no
APIscaminho é fechada na ramificação principal. - O local da definição é extraído da solicitação pull usando um script 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 com um nome como
register-api.yml. - Atualize os valores das variáveis de ambiente para que correspondam ao seu centro de API no Azure.
- Confirme ou atualize o nome da pasta do repositório (
APIs) onde você adicionará o arquivo de definição da API. - Adicione este arquivo de fluxo de trabalho no caminho do
/.github/workflows/repositório GitHub.
Gorjeta
Usando a extensão de código do Visual Studio 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 Central de APIs 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 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 ramificações do GitHub, consulte a documentação do GitHub.
Crie uma nova ramificação de trabalho a partir da ramificação principal em seu repositório.
Adicione o arquivo de definição de API ao repositório no
APIscaminho. Por exemplo,APIs/catfacts-api/07-15-2024.json.Confirme as alterações e envie-as para a ramificação de trabalho.
Crie uma solicitação pull para mesclar a ramificação de trabalho na ramificação principal.
Após a revisão, mescle a solicitação pull. A mesclagem aciona o fluxo de trabalho de Ações do GitHub que registra a API em seu centro de APIs.
Verificar o registro da API
Verifique se a API está registrada no seu centro de APIs.
- No portal do Azure, navegue até o centro de APIs.
- No menu à esquerda, em Ativos, selecione APIs.
- Verifique se a API recém-registrada aparece na lista de APIs.
Adicionar uma nova versão da API
Para adicionar uma nova versão a uma API existente no seu centro de APIs, siga as etapas anteriores, com uma pequena modificação:
- Mude para a mesma ramificação 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
APIscaminho, na pasta de uma API existente. Por exemplo, se você adicionou anteriormente uma definição da API Cat Facts, adicione uma nova versão, comoAPIs/catfacts-api/07-22-2024.json. - Confirme as alterações e envie-as para a ramificação de trabalho.
- Crie uma solicitação pull para mesclar a ramificação de trabalho na ramificação principal.
- Após a revisão, mescle a solicitação pull. A mesclagem aciona o fluxo de trabalho de Ações do GitHub que registra a nova versão da API em seu 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 de Ações do GitHub para incluir outras etapas, como adicionar metadados para o registro da 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 seu registro de API.
Por exemplo, se o esquema de metadados incluir propriedades como
approver,teamecost 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 de cada API no repositório.
Adicione uma etapa de fluxo de trabalho para aplicar os metadados ao registro da API usando o comando az apic api update . No exemplo a seguir, o 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 }}