Share via

Importare API nel centro API da Azure Gestione API

  • Articolo

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:

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:

    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 viene installata in modo dinamico quando si esegue il primo comando az apic. 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.

  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.

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.

  1. Nel portale, passare all'istanza di Gestione API.
  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 lettore Gestione API servizio.
    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.

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.

  1. 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)

  2. 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.

  1. 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)

  2. 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