Sincronizar APIs do Amazon API Gateway com o Centro de APIs do Azure (versão prévia)

Este artigo mostra como integrar um Amazon API Gateway para manter as APIs do gateway sempre atualizadas no inventário do Centro de APIs.

Sobre a integração do Amazon API Gateway

Integrar o Amazon API Gateway como uma fonte de API com o Centro de APIs permite uma sincronização contínua, garantindo que o inventário de APIs permaneça atualizado. O Centro de APIs do Azure também pode sincronizar APIs de fontes como o Gerenciamento de API do Azure.

Quando você integra um Amazon API Gateway como uma fonte de API, ocorre o seguinte:

1. As APIs e, opcionalmente, as definições de API (especificações), do Gerenciamento de API, são adicionadas ao inventário do Centro de APIs.
2. Você configura um ambiente do tipo Amazon API Gateway no Centro de APIs.
3. Uma implantação associada é criada para cada definição de API sincronizada.

Essa sincronização é unidirecional do Amazon API Gateway para o Centro de APIs do Azure, ou seja, atualizações de API feitas no Centro de APIs não são sincronizadas de volta com o Amazon API Gateway.

Observação

• No momento, a integração do Amazon API Gateway está em versão prévia.
• Existem limites para o número de fontes de API que podem ser integradas.
• As APIs no Amazon API Gateway são sincronizadas com o Centro de APIs uma vez por hora. Somente as APIs REST são sincronizadas.
• As definições das APIs também serão sincronizadas com o Centro de APIs se você selecionar a opção de incluí-las durante a integração. Apenas definições de APIs implantadas são sincronizadas.

Entidades sincronizadas do Amazon API Gateway

Você pode adicionar ou atualizar propriedades de metadados e documentação nas APIs sincronizadas no seu Centro de APIs, facilitando que os stakeholders descubram, compreendam e utilizem essas APIs. Saiba mais sobre as propriedades de metadados internas e personalizadas do Centro de API do Azure.

A tabela a seguir apresenta as propriedades da entidade que podem ser modificadas no Centro de APIs do Azure, bem como aquelas definidas com base nos valores provenientes da fonte de API integrada.

Entity	Propriedades configuráveis no Centro de API	Propriedades determinadas na fonte de API integrada
API	summary lifecycleStage termsOfService license externalDocumentation customProperties	title descrição kind
Versão da API	lifecycleStage	title definições (se sincronizadas)
Ambiente	title descrição kind server.managementPortalUri integração customProperties	server.type
Implantação	title descrição servidor estado customProperties	server.runtimeUri

Observação

IDs de recursos e do sistema para entidades sincronizadas com o Centro de APIs do Azure são geradas automaticamente e não podem ser alteradas.

Pré-requisitos

• Um centro de API na sua assinatura do Azure. Se você não criou um, consulte Início Rápido: criar seu centro de API.

• Um cofre de chaves do Azure. Se precisar criar uma, confira a página Início Rápido: criar um Azure Key Vault usando o portal do Azure. Para adicionar ou gerenciar segredos no cofre de chaves, é necessário ter, pelo menos, a função Key Vault Secrets Officer ou permissões equivalentes.

• Um Amazon API Gateway.

• Uma identidade de usuário do IAM da AWS com a política AmazonAPIGatewayAdministrator anexada.

• 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. Alguns recursos podem exigir uma versão prévia ou específica da extensão.

  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.

Criar chaves de acesso para usuário do IAM

Para autenticar seu Centro de APIs no Amazon API Gateway, você precisa de chaves de acesso para um usuário do IAM da AWS.

Para gerar a ID da chave de acesso e a chave secreta necessárias usando o AWS Management Console, confira a página Criar uma chave de acesso para você mesmo na documentação da AWS.

Salve suas chaves de acesso em um local seguro. Você as armazenará no Azure Key Vault nas próximas etapas.

Cuidado

As chaves de acesso são credenciais de longo prazo e você deve gerenciá-las com a mesma segurança de uma senha. Saiba mais sobre como proteger chaves de acesso

Armazenar chaves de acesso de usuário do IAM no Azure Key Vault

Carregue e armazene manualmente e com segurança as duas chaves de acesso do usuário do IAM no Azure Key Vault, usando a configuração recomendada na tabela a seguir. Para saber mais, confira a página Início Rápido: definir e recuperar um segredo do Azure Key Vault usando o portal do Azure.

Segredo da AWS	Opções de upload	Nome	Valor do segredo
Chave de acesso	Manual	aws-access-key	ID da chave de acesso recuperada da AWS
Chave de acesso do segredo	Manual	aws-secret-access-key	Chave secreta de acesso recuperada da AWS

Anote cada Identificador de segredo, um URI semelhante a https://<key-vault-name>.vault.azure.net/secrets/<secret-name>. Você usará esses identificadores nas próximas etapas.

Habilitar uma identidade gerenciada em seu Centro de APIs

Para esse cenário, o Centro de APIs usa uma identidade gerenciada para acessar os recursos do Azure. Dependendo das suas necessidades, habilite uma identidade gerenciada atribuída pelo sistema ou uma ou mais identidades gerenciadas atribuídas pelo usuário.

Os exemplos a seguir mostram como habilitar uma identidade gerenciada atribuída pelo sistema usando o portal do Azure ou a CLI do Azure. A um nível elevado, os passos de configuração são semelhantes para uma identidade gerida atribuída pelo utilizador.

Portal

1. No portal, navegue até seu centro de API.
2. No menu à esquerda, em Segurança, selecione Identidades Gerenciadas.
3. Selecione Sistema atribuído e defina o status como Ativado.
4. Selecione Salvar.

CLI do Azure

Defina a identidade atribuída pelo sistema no centro de API usando o seguinte comando az apic update. Substitua os nomes do centro de API e do grupo de recursos:

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

Atribuir a função Key Vault Secrets User à identidade gerenciada

Para permitir a importação de APIs, atribua à identidade gerenciada do seu Centro de APIs a função Key Vault Secrets User no cofre de chaves do Azure. É possível usar o portal ou a CLI do Azure.

Portal

1. No portal, navegue até o cofre de chaves.
2. No menu à esquerda, selecione Controle de acesso (IAM) .
3. Escolha Adicionar atribuição de função.
4. Na página Adicionar atribuição de função, defina os valores da seguinte maneira:
   1. Na guia Função, selecione Usuário de Segredos do Key Vault.
   2. Na guia Membros, em Atribuir acesso a – Selecione Identidade Gerenciada > + Selecionar membros.
   3. Na página Selecionar identidades gerenciadas, selecione a identidade gerenciada atribuída pelo sistema ao Centro de APIs que você adicionou na seção anterior. Clique em Selecionar.
   4. Selecione Examinar + atribuir.

CLI do Azure

1. Obtenha a ID da entidade de segurança da identidade. Para uma identidade atribuída pelo sistema, use o comando az apic show.

   #! /bin/bash
   apicObjID=$(az apic show --name <api-center-name> \
       --resource-group <resource-group-name> \
       --query "identity.principalId" --output tsv)
   

   # Formatted for PowerShell
   $apicObjID=$(az apic show --name <api-center-name> `
       --resource-group <resource-group-name> `
       --query "identity.principalId" --output tsv)
   

2. Obtenha a ID do recurso do seu cofre de chaves usando o comando az keyvault show.

   #! /bin/bash
   kvID=$(az keyvault show --name <kv-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

   # Formatted for PowerShell
   $kvID=$(az keyvault show --name <kv-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

3. Atribua a função Key Vault Secrets User à identidade gerenciada no seu cofre de chaves usando o comando az role assignment create.

   #! /bin/bash
   scope="${kvID:1}"
   
   az role assignment create \
       --role "Key Vault Secrets User" \
       --assignee-object-id $apicObjID \
       --assignee-principal-type ServicePrincipal \
       --scope $scope 
   

   # Formatted for PowerShell
   $scope=$apimID.substring(1)
   
   az role assignment create `
       --role "Key Vault Secrets User" `
       --assignee-object-id $apicObjID `
       --assignee-principal-type ServicePrincipal `
       --scope $scope 
   

Integrar um Amazon API Gateway

Execute o comando az apic integration create aws (em versão prévia) para integrar um Amazon API Gateway ao seu Centro de APIs.

• Forneça os nomes do grupo de recursos, do Centro de APIs e da integração.

• Forneça os identificadores de segredos do Key Vault para a chave de acesso da AWS e a chave de acesso secreta, além da região da AWS onde o Amazon API Gateway está implantado.

az apic integration create aws \
    --resource-group <resource-group-name> \
    --service-name-name <api-center-name> \
    --integration-name <aws-integration-name> \
    --aws-access-key-reference <access-key-uri> \
    --aws-secret-access-key-reference <secret-access-key-uri> 
    --aws-region-name <aws-region>

---

O ambiente é adicionado ao centro de API. As APIs do Amazon API Gateway são importadas para o inventário do Centro de APIs.

Excluir uma integração

Enquanto uma fonte de API estiver integrada, você não poderá excluir APIs sincronizadas a partir do seu Centro de APIs. Se você precisar, poderá excluir a integração. Ao excluir uma integração:

• As APIs sincronizadas no inventário do Centro de APIs são excluídas
• O ambiente e as implantações associadas à fonte de API são excluídos

Para excluir uma integração usando a CLI do Azure, execute o comando az apic integration delete (em versão prévia). Forneça os nomes do grupo de recursos, do Centro de APIs e da integração.

az apic integration delete \
    --resource-group <resource-group-name> \
    --service-name <api-center-name> \
    --integration-name <integration-name> 

Conteúdo relacionado

• Gerenciar o inventário de API com comandos da CLI do Azure
• Sincronizar APIs do Gerenciamento de API para o Centro de APIs do Azure