Sincronizzare le API da Amazon API Gateway al Centro API di Azure (anteprima)

Questo articolo illustra come integrare un gateway API Amazon in modo che le API del gateway siano costantemente aggiornate nell'inventario del centro API.

Informazioni sull'integrazione di Amazon API Gateway

L'integrazione di Amazon API Gateway come origine API per il centro API consente la sincronizzazione continua in modo che l'inventario API rimanga aggiornato. Il Centro API di Azure può anche sincronizzare le API da origini, tra cui Azure Gestione API.

Quando si integra amazon API Gateway come origine API, si verifica quanto segue:

1. Le API e, facoltativamente, le definizioni API (specifiche), dal gateway API vengono aggiunte all'inventario del centro API.
2. Configurare un ambiente di tipo Amazon API Gateway nel centro API.
3. Viene creata una distribuzione associata per ogni definizione dell'API sincronizzata.

La sincronizzazione è unidirezionale da Amazon API Gateway al centro API di Azure, ovvero gli aggiornamenti api nel centro API non vengono sincronizzati con Amazon API Gateway.

Nota

• L'integrazione di Amazon API Gateway è attualmente in anteprima.
• Esistono limiti per il numero di origini API integrate.
• Le API in Amazon API Gateway vengono sincronizzate con il centro API una volta all'ora. Vengono sincronizzate solo le API REST.
• Le definizioni API vengono sincronizzate anche con il centro API se si seleziona l'opzione per includerle durante l'integrazione. Vengono sincronizzate solo le definizioni delle API distribuite.

Entità sincronizzate da Amazon API Gateway

È possibile aggiungere o aggiornare le proprietà e la documentazione dei metadati alle API sincronizzate nel centro API per aiutare gli stakeholder a individuare, comprendere e usare le API. Altre informazioni sulle proprietà predefinite e personalizzate dei metadati del Centro API di Azure.

La tabella seguente illustra le proprietà dell'entità che possono essere modificate nel Centro API di Azure e le proprietà impostate in base ai relativi valori nell'origine API.

Entità	Proprietà configurabili nel Centro API	Proprietà determinate nell'origine API integrata
API (Interfaccia di Programmazione delle Applicazioni)	riepilogo Fase del ciclo di vita Termini di servizio Licenza documentazione esterna Proprietà personalizzate	titolo descrizione tipo/gentile
Versione dell'API	Fase del ciclo di vita	titolo definizioni (se sincronizzate)
Ambiente	titolo descrizione kind server.managementPortalUri inserimento Proprietà personalizzate	server.type
Distribuzione	titolo descrizione server stato Proprietà personalizzate	server.runtimeUri

Nota

Gli ID risorsa e di sistema per le entità sincronizzate nel Centro API di Azure vengono generati automaticamente e non possono essere modificati.

Prerequisiti

• Un centro API nella sottoscrizione di Azure. Se non ne è stato creato uno, vedere Guida introduttiva: Creare il centro API.

• Un insieme di credenziali delle chiavi di Azure. Se è necessario crearne uno, vedere Avvio rapido: Creare un insieme di credenziali delle chiavi usando il portale di Azure. Per aggiungere o gestire segreti nell'insieme di credenziali delle chiavi, è necessario almeno il ruolo Di responsabile dei segreti dell'insieme di credenziali delle chiavi o autorizzazioni equivalenti.

• Un gateway API Amazon.

• Un'identità utente di AWS IAM con i AmazonAPIGatewayAdministrator criteri associati.

• Per l'interfaccia della riga di comando di Azure:

  • Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Introduzione ad Azure Cloud Shell.

    

  • Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.

    • Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Eseguire l'autenticazione ad Azure con l'interfaccia della riga di comando di Azure.

    • Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare e gestire le estensioni con l'interfaccia della riga di comando di Azure.

    • Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

  Nota

  I comandi az apic richiedono l'estensione dell'interfaccia della riga di comando di Azure apic-extension. Se non sono stati usati comandi az apic, l'estensione può essere installata in modo dinamico quando si esegue il primo comando az apic oppure è possibile installarla manualmente. Altre informazioni sulle estensioni dell'interfaccia della riga di comando di Azure.

  Vedere le note sulla versione per le modifiche e gli aggiornamenti più recenti in apic-extension. Alcune funzionalità possono richiedere un'anteprima o una versione specifica dell'estensione.

  Nota

  Gli esempi di comandi dell'interfaccia della riga di comando di Azure riportati in questo articolo possono essere eseguiti in PowerShell o in una shell bash. Se necessario, a causa di una sintassi di variabile diversa, vengono forniti esempi di comandi separati per le due shell.

Creare chiavi di accesso utente IAM

Per autenticare il centro API in Amazon API Gateway, sono necessarie chiavi di accesso per un utente AWS IAM.

Per generare l'ID chiave di accesso e la chiave privata necessari usando AWS Management Console, vedere Creare manualmente una chiave di accesso nella documentazione di AWS.

Salvare le chiavi di accesso in una posizione sicura. Questi verranno archiviati in Azure Key Vault nei passaggi successivi.

Attenzione

Le chiavi di accesso sono credenziali a lungo termine e devono essere gestite in modo sicuro come si farebbe con una password. Altre informazioni sulla protezione delle chiavi di accesso

Archiviare le chiavi di accesso utente IAM in Azure Key Vault

Caricare e archiviare in modo sicuro le due chiavi di accesso utente IAM in Azure Key Vault usando la configurazione consigliata nella tabella seguente. Per altre informazioni, vedere Avvio rapido: Impostare e recuperare un segreto da Azure Key Vault usando il portale di Azure.

Segreto AWS	Opzioni di caricamento	Nome	Valore segreto
Chiave di accesso	Manuale	aws-access-key	ID chiave di accesso recuperato da AWS
Chiave di accesso privata	Manuale	Chiave di accesso segreta AWS	Chiave di accesso privata recuperata da AWS

Prendere nota dell'identificatore segreto di ogni segreto, un URI simile a https://<key-vault-name>.vault.azure.net/secrets/<secret-name>. Questi identificatori verranno usati nei passaggi successivi.

Abilitare un'identità gestita nel centro API

Per questo scenario, il centro API usa un'identità gestita per accedere alle risorse di Azure. A seconda delle esigenze, abilitare un'identità gestita assegnata dal sistema o una o più identità gestite assegnate dall'utente.

Gli esempi seguenti illustrano come abilitare un'identità gestita assegnata dal sistema usando il portale di Azure o l'interfaccia della riga di comando di Azure. A livello generale, i passaggi di configurazione sono simili per un'identità gestita assegnata dall'utente.

Portale

1. Nel portale, passare al centro API.
2. Nel menu a sinistra, in Sicurezzaselezionare Identità gestite.
3. Selezionare Sistema assegnato e impostare lo stato su Sì.
4. Seleziona Salva.

Interfaccia della riga di comando di Azure

Impostare l'identità assegnata dal sistema nel centro API usando il comando az apic update seguente. Sostituire i nomi del centro API e del gruppo di risorse:

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

Assegnare l'identità gestita al ruolo utente Segreti di Key Vault

Per consentire l'importazione delle API, assegnare l'identità gestita del centro API al ruolo Utente segreti di Key Vault nell'insieme di credenziali delle chiavi di Azure. È possibile usare il portale o l'interfaccia della riga di comando di Azure.

Portale

1. Nel portale passare all'insieme di credenziali delle chiavi.
2. Nel menu a sinistra selezionare Controllo di accesso (IAM).
3. Selezionare + Aggiungi assegnazione di ruolo.
4. Nella pagina Aggiungi assegnazione di ruolo, impostare i valori come segue:
   1. Nella scheda Ruolo, selezionare Utente dei segreti Key Vault.
   2. Nella scheda Membri, in Assegnare l'accesso a - Selezionare Identitàgestita>+ Seleziona membri.
   3. Nella pagina Seleziona identità gestite selezionare l'identità gestita assegnata dal sistema del centro API aggiunto nella sezione precedente. Fare clic su Seleziona.
   4. Seleziona Rivedi + assegna.

Interfaccia della riga di comando di Azure

1. Ottenere l'ID entità dell'identità. Per un'identità assegnata dal sistema, usare il 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. Ottenere l'ID risorsa dell'insieme di credenziali delle chiavi usando il 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. Assegnare l'identità gestita al ruolo utente segreti di Key Vault nell'insieme di credenziali delle chiavi il 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 
   

Integrare un gateway API Amazon

È possibile integrare un gateway API Amazon usando il portale o l'interfaccia della riga di comando di Azure.

Portale

1. Nel portale, passare al centro API.
2. In Piattaforme selezionare Integrazioni.
3. Selezionare + Nuova integrazione>da Amazon API Gateway.
4. Nella pagina Integrare il servizio Amazon API Gateway :
   1. Per la chiave di accesso AWS e la chiave di accesso privata AWS, fare clic su Seleziona e selezionare la sottoscrizione, l'insieme di credenziali delle chiavi, il segreto archiviato.
   2. Selezionare l'area AWS in cui viene distribuito Amazon API Gateway.
   3. In Dettagli integrazione immettere un identificatore.
   4. In Dettagli ambiente immettere un titolo ambiente (nome), tipo di ambiente e Descrizione facoltativa.
   5. In Dettagli API:
      1. Selezionare un ciclo di vita per le API sincronizzate. È possibile aggiornare questo valore per le API dopo l'aggiunta al centro API.
      2. Facoltativamente, selezionare se includere definizioni api con le API sincronizzate.
5. Fare clic su Crea.

Interfaccia della riga di comando di Azure

Eseguire il comando az apic integration create aws (anteprima) per integrare amazon API Gateway nel centro API.

• Specificare i nomi del gruppo di risorse, del centro API e dell'integrazione.

• Specificare gli identificatori dei segreti di Key Vault per la chiave di accesso e la chiave di accesso privata AWS e l'area AWS in cui viene distribuito Amazon API Gateway.

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>

L'ambiente viene aggiunto nel centro API. Le API di Amazon API Gateway vengono importate nell'inventario del centro API.

Eliminare un'integrazione

Mentre un'origine API è integrata, non è possibile eliminare le API sincronizzate dal centro API. Se necessario, è possibile eliminare l'integrazione. Quando si elimina un'integrazione:

• Le API sincronizzate nell'inventario del centro API vengono eliminate
• L'ambiente e le distribuzioni associate all'origine API vengono eliminate

È possibile eliminare un'integrazione usando il portale o l'interfaccia della riga di comando di Azure.

Portale

1. Nel portale, passare al centro API.
2. In Asset, selezionare Ambienti>Integrazioni (anteprima).
3. Selezionare l'integrazione e quindi elimina (icona del cestino).

Interfaccia della riga di comando di Azure

Eseguire il comando az apic integration delete (anteprima) per eliminare un'integrazione. Specificare i nomi del gruppo di risorse, del centro API e dell'integrazione.

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

Contenuto correlato

• Gestire l'inventario API con i comandi dell'interfaccia della riga di comando di Azure
• Sincronizzare le API da Gestione API al centro API di Azure