Importare API nel centro API da Azure Gestione API
Questo articolo illustra come importare (aggiungere) API da un'istanza di Azure Gestione API al centro API usando l'interfaccia della riga di comando di Azure. L'aggiunta di API da Gestione API all'inventario API consente di renderle individuabili e accessibili agli sviluppatori, ai responsabili dei programmi API e ad altri stakeholder dell'organizzazione.
Questo articolo illustra due opzioni per l'uso dell'interfaccia della riga di comando di Azure per aggiungere API al centro API da Gestione API:
Opzione 1: esportare una definizione API da un'istanza di Gestione API usando il comando az apim api export. Importare quindi la definizione nel centro API.
I possibili modi per importare una definizione API esportata da Gestione API includono:
- Eseguire az apic api register per registrare una nuova API nel centro API.
- Eseguire az apic api definition import-specification per importare la definizione dell'API in un'API esistente.
Opzione 2: importare le API direttamente da Gestione API al centro API usando il comando az apic service import-from-apim.
Dopo aver importato le definizioni api o le API da Gestione API, è possibile aggiungere metadati e documentazione nel centro API per aiutare gli stakeholder a individuare, comprendere e usare l'API.
Prerequisiti
Un centro API nella sottoscrizione di Azure. Se non ne è stato creato uno, vedere Avvio rapido: Creare il centro API.
Una o più istanze di Azure Gestione API, nella stessa sottoscrizione o in una sottoscrizione diversa. Quando si importano API direttamente da Gestione API, l'istanza di Gestione API e il centro API devono trovarsi nella stessa directory. Se non ne è stato creato uno, vedere Creare un'istanza di Azure Gestione API.
Una o più API gestite nell'istanza di Gestione API che si vuole aggiungere al centro API.
Per l'interfaccia della riga di comando di Azure:
Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido su Bash in 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 Accedere tramite 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 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 Azureapic-extension
. Se non sono stati usatiaz apic
comandi, l'estensione può essere installata in modo dinamico quando si esegue il primoaz apic
comando oppure è possibile installare l'estensione manualmente. Altre informazioni sulle estensioni dell'interfaccia della riga di comando di Azure.Nota
Gli esempi di comandi dell'interfaccia della riga di comando di Azure 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.
Opzione 1: Esportare una definizione API da Gestione API e importarla nel centro API
Prima di tutto, esportare un'API dall'istanza di Gestione API a una definizione API usando il comando az apim api export. A seconda dello scenario, è possibile esportare la definizione dell'API in un file locale o in un URL.
Esportare l'API in un file di definizione dell'API locale
Il comando di esempio seguente esporta l'API con identificatore my-api nell'istanza myAPIManagement dell'API. L'API viene esportata in formato OpenApiJson in un file di definizione OpenAPI locale denominato specificationFile.json.
#! /bin/bash
az apim api export --api-id my-api --resource-group myResourceGroup \
--service-name myAPIManagement --export-format OpenApiJsonFile \
--file-path "/path/to/folder"
#! PowerShell syntax
az apim api export --api-id my-api --resource-group myResourceGroup `
--service-name myAPIManagement --export-format OpenApiJsonFile `
--file-path '/path/to/folder'
Esportare l'API in un URL
Nell'esempio seguente az apim api export esporta l'API con identificatore my-api in formato OpenApiJson in un URL in Archiviazione di Azure. L'URL è disponibile per circa 5 minuti. In questo caso, il valore dell'URL viene archiviato nella variabile $link .
#! /bin/bash
link=$(az apim api export --api-id my-api --resource-group myResourceGroup \
--service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
--output tsv)
# PowerShell syntax
$link=$(az apim api export --api-id my-api --resource-group myResourceGroup `
--service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link `
--output tsv)
Registrare l'API nel centro API dalla definizione dell'API esportata
È possibile registrare una nuova API nel centro API dalla definizione esportata usando il comando az apic api register .
L'esempio seguente registra un'API nel centro API myAPICenter da un file di definizione OpenAPI locale denominato definitionFile.json.
az apic api register --resource-group myResourceGroup --service myAPICenter --api-location "/path/to/definitionFile.json"
Importare la definizione dell'API in un'API esistente nel centro API
L'esempio seguente usa il comando az apic api definition import-specification per importare una definizione API in un'API esistente nel centro API myAPICenter . In questo caso, la definizione dell'API viene importata da un URL archiviato nella variabile $link .
Questo esempio presuppone che l'API sia denominata my-api e una versione API 1-0-0 associata e l'entità di definizione openapi nel centro API. In caso contrario, vedere Aggiungere API al centro API.
#! /bin/bash
az apic api definition import-specification \
--resource-group myResourceGroup --service myAPICenter \
--api-id my-api --version-id v1-0-0 \
--definition-id openapi --format "link" --value '$link' \
--specification '{"name":"openapi","version":"3.0.2"}'
# PowerShell syntax
az apic api definition import-specification `
--resource-group myResourceGroup --service myAPICenter `
--api-id my-api --version-id v1-0-0 `
--definition-id openapi --format "link" --value '$link' `
--specification '{"name":"openapi","version":"3.0.2"}'
Opzione 2: Importare API direttamente dall'istanza di Gestione API
Di seguito sono riportati i passaggi per importare le API dall'istanza di Gestione API al centro API usando il comando az apic service import-from-apim. Questo comando è utile quando si vogliono importare più API da Gestione API al centro API, ma è anche possibile usarlo per importare una singola API.
Quando si aggiungono API da un'istanza di Gestione API al centro API usando az apic service import-from-apim
, si verifica automaticamente quanto segue:
- Le versioni, le definizioni e le informazioni sulla distribuzione di ogni API vengono copiate nel centro API.
- L'API riceve un nome API generato dal sistema nel centro API. Mantiene il nome visualizzato (titolo) da Gestione API.
- La fase del ciclo di vita dell'API è impostata su Progettazione.
- Azure Gestione API viene aggiunto come ambiente.
Aggiungere un'identità gestita nel centro API
Per questo scenario, il centro API usa un'identità gestita per accedere alle API nell'istanza di Gestione API. A seconda delle esigenze, configurare un'identità gestita assegnata dal sistema o una o più identità gestite assegnate dall'utente.
Gli esempi seguenti illustrano come configurare 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.
- Nel portale passare al centro API.
- Nel menu a sinistra, in Sicurezzaselezionare Identità gestite.
- Selezionare Sistema assegnato e impostare lo stato su Sì.
- Seleziona Salva.
Assegnare l'identità gestita al ruolo lettore del servizio Gestione API
Per consentire l'importazione delle API, assegnare all'identità gestita del centro API il ruolo lettore del servizio di Gestione API nell'istanza di Gestione API. È possibile usare il portale o l'interfaccia della riga di comando di Azure.
- Nel portale, andare all'istanza di API Management.
- Nel menu a sinistra selezionare Controllo di accesso (IAM).
- Selezionare + Aggiungi assegnazione di ruolo.
- Nella pagina Aggiungi assegnazione di ruolo impostare i valori come segue:
- Nella scheda Ruolo selezionare lettore Gestione API servizio.
- Nella scheda Membri, in Assegnare l'accesso a - Selezionare Identità> gestita+ Seleziona membri.
- Nella pagina Seleziona identità gestite selezionare l'identità gestita assegnata dal sistema del centro API aggiunto nella sezione precedente. Fare clic su Seleziona.
- Seleziona Rivedi + assegna.
Importare API da Gestione API
Usare il comando az apic service import-from-apim per importare una o più API dall'istanza di Gestione API al centro API.
Nota
Questo comando dipende da un'identità gestita configurata nel centro API con autorizzazioni di lettura per l'istanza di Gestione API. Se non è stata aggiunta o configurata un'identità gestita, vedere Aggiungere un'identità gestita nel centro API in precedenza in questo articolo.
Se il centro API ha più identità gestite, il comando cerca innanzitutto un'identità assegnata dal sistema. Se non viene trovato alcun elemento, seleziona la prima identità assegnata dall'utente nell'elenco.
Importare tutte le API da un'istanza di Gestione API
Usare un carattere jolly (*
) per specificare tutte le API dell'istanza di Gestione API.
Ottenere l'ID risorsa dell'istanza di Gestione API usando il comando az apim show.
#! /bin/bash apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)
# PowerShell syntax $apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)
Usare il
az apic service import-from-apim
comando per importare le API. Sostituire i nomi del centro API e del gruppo di risorse e usare*
per specificare tutte le API dell'istanza di Gestione API.az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/*
Nota
Se l'istanza di Gestione API ha un numero elevato di API, l'importazione nel centro API potrebbe richiedere del tempo.
Importare un'API specifica da un'istanza di Gestione API
Specificare un'API da importare usando il relativo nome dall'istanza di Gestione API.
Ottenere l'ID risorsa dell'istanza di Gestione API usando il comando az apim show.
#! /bin/bash apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)
# PowerShell syntax $apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)
Usare il
az apic service import-from-apim
comando per importare l'API. Sostituire i nomi del centro API e del gruppo di risorse e specificare un nome API dall'istanza di Gestione API.az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/<api-name>
Nota
Specificare
<api-name>
l'uso del nome della risorsa API nell'istanza di Gestione API, non il nome visualizzato. Esempio:petstore-api
anzichéPetstore API
.
Dopo l'importazione di API da Gestione API, è possibile visualizzare e gestire le API importate nel centro API.
Contenuto correlato
- Informazioni di riferimento dell'interfaccia della riga di comando di Azure per il Centro API di Azure
- Informazioni di riferimento dell'interfaccia della riga di comando di Azure per Gestione API
- Gestire l'inventario API con i comandi dell'interfaccia della riga di comando di Azure
- Assegnare ruoli di Azure a un'identità gestita
- Documentazione di Azure Gestione API
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per