Esercitazione: Creare e pubblicare un prodotto

SI APPLICA A: Tutti i livelli di Gestione API

In Gestione API di Azure un prodotto contiene una o più API, una quota di utilizzo e le condizioni per l'utilizzo. Dopo la pubblicazione di un prodotto, gli sviluppatori possono eseguire la sottoscrizione al prodotto e iniziare a usare le API del prodotto.

In questa esercitazione apprenderai a:

• Creare e pubblicare un prodotto
• Aggiungere un'API al prodotto
• Accedere alle API del prodotto

Prerequisiti

• Acquisire familiarità con la terminologia di Gestione API di Azure.
• Completare la guida introduttiva seguente: Creare un'istanza di Gestione API di Azure.
• Completare anche l'esercitazione seguente: Importare e pubblicare la prima API.

Creare e pubblicare un prodotto

Portale

1. Accedere al portale di Azure e passare all'istanza di Gestione API.

2. Nel riquadro di spostamento a sinistra selezionare Prodotti>+ Aggiungi.

   

3. Nella finestra Aggiungi prodotto immettere i valori descritti nella tabella seguente per creare il prodotto.

   

   Nome	Descrizione
   Display name	Nome che dovrà essere visualizzato nel portale per sviluppatori.
   Descrizione	Consente di specificare informazioni sul prodotto, ad esempio lo scopo, le API a cui fornisce l'accesso e altri dettagli.
   Provincia	Selezionare Pubblicato se si vuole pubblicare il prodotto. Per poter chiamare le API in un prodotto, il prodotto deve essere pubblicato. Per impostazione predefinita, i nuovi prodotti non sono pubblicati e sono visibili solo agli utenti nel gruppo Amministratori.
   Richiede la sottoscrizione	Selezionare se è necessario che un utente sottoscriva l'uso del prodotto (il prodotto è protetto) e che si usi una chiave di sottoscrizione per accedere alle API del prodotto. Se non è necessaria una sottoscrizione (il prodotto è aperto), non è necessaria una chiave di sottoscrizione per accedere alle API del prodotto. Vedere Accedere alle API del prodotto più avanti in questo articolo.
   Richiede approvazione	Specificare se si preferisce che i tentativi di sottoscrizione del prodotto vengano esaminati e quindi accettati o rifiutati da un amministratore. Se l'opzione non è selezionata, i tentativi di sottoscrizione vengono approvati automaticamente.
   Limite per il numero di sottoscrizioni	Consente di limitare il numero di più sottoscrizioni simultanee.
   Note legali	È possibile includere le condizioni per l'utilizzo del prodotto che i sottoscrittori devono accettare per usare il prodotto.
   API	Selezionare una o più API. È anche possibile aggiungere le API dopo la creazione del prodotto. Per altre informazioni, vedere Aggiungere API a un prodotto più avanti in questo articolo. Se il prodotto è aperto (non richiede un abbonamento), è possibile aggiungere solo un'API non associata a un altro prodotto aperto.

4. Fare clic su Crea per creare il nuovo prodotto.

Attenzione

Prestare attenzione durante la configurazione di un prodotto che non richiede una sottoscrizione. Questa configurazione può essere eccessivamente permissiva e può rendere le API del prodotto più vulnerabili a determinate minacce per la sicurezza delle API.

Interfaccia della riga di comando di Azure

Per iniziare a usare l'interfaccia della riga di comando di Azure:

• Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere la Avvio rapido di 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.

Per creare un prodotto, eseguire il comando az apim product create:

az apim product create --resource-group apim-hello-word-resource-group \
    --product-name "Contoso product" --product-id contoso-product \
    --service-name apim-hello-world --subscription-required true \
    --state published --description "This is a test."

È possibile specificare vari valori per il prodotto:

Parametro	Descrizione
--product-name	Nome che dovrà essere visualizzato nel portale per sviluppatori.
--description	Consente di specificare informazioni sul prodotto, ad esempio lo scopo, le API a cui fornisce l'accesso e altri dettagli.
--state	Selezionare pubblicato se si vuole pubblicare il prodotto. Per poter chiamare le API in un prodotto, il prodotto deve essere pubblicato. Per impostazione predefinita, i nuovi prodotti non sono pubblicati e sono visibili solo agli utenti nel gruppo Amministratori.
--subscription-required	Selezionare se è necessario che un utente sottoscriva l'uso del prodotto (il prodotto è protetto) o che non sia necessaria una sottoscrizione (il prodotto è aperto). Vedere Accedere alle API del prodotto più avanti in questo articolo.
--approval-required	Specificare se si preferisce che i tentativi di sottoscrizione del prodotto vengano esaminati e quindi accettati o rifiutati da un amministratore. Se l'opzione non è selezionata, i tentativi di sottoscrizione vengono approvati automaticamente.
--subscriptions-limit	Consente di limitare il numero di più sottoscrizioni simultanee.
--legal-terms	È possibile includere le condizioni per l'utilizzo del prodotto che i sottoscrittori devono accettare per usare il prodotto.

Attenzione

Prestare attenzione durante la configurazione di un prodotto che non richiede una sottoscrizione. Questa configurazione può essere eccessivamente permissiva e può rendere le API del prodotto più vulnerabili a determinate minacce per la sicurezza delle API.

Per visualizzare i prodotti correnti, usare il comando az apim product list:

az apim product list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

È possibile eliminare un prodotto usando il comando az apim product delete:

az apim product delete --product-id contoso-product \
    --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --delete-subscriptions true

Aggiungere altre configurazioni

Continuare a configurare il prodotto dopo averlo salvato. Nell'istanza di Gestione API selezionare il prodotto dalla finestra Prodotti. Aggiungere o aggiornare:

Articolo	Descrizione
Impostazione	Metadati e stato del prodotto
API	API associata a un prodotto
Criteri	Criteri applicati alle API del prodotto
Controllo di accesso	Visibilità del prodotto per sviluppatori o utenti guest
Sottoscrizioni	Sottoscrittori del prodotto

Aggiungere API a un prodotto

I prodotti sono associazioni di una o più API. È possibile includere diverse API e proporle agli sviluppatori tramite il portale per sviluppatori. Durante la creazione del prodotto, è possibile aggiungere una o più API esistenti. È anche possibile aggiungere API al prodotto in un secondo momento, dalla pagina Impostazioni dei prodotti o durante la creazione di un'API.

Aggiungere un'API a un prodotto esistente

Portale

1. Nel riquadro di spostamento a sinistra dell'istanza di Gestione API selezionare Prodotti.
2. Selezionare un prodotto, quindi selezionare API.
3. Selezionare + Aggiungi API.
4. Selezionare una o più API e quindi fare clic su Seleziona.

Interfaccia della riga di comando di Azure

1. Per visualizzare le API gestite, usare il comando az apim api list:

   az apim api list --resource-group apim-hello-word-resource-group \
       --service-name apim-hello-world --output table
   

2. Per aggiungere un'API al prodotto, eseguire il comando az apim product api add:

   az apim product api add --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --product-id contoso-product \
       --service-name apim-hello-world
   

3. Verificare l'aggiunta usando il comando az apim product api list:

   az apim product api list --resource-group apim-hello-word-resource-group \
       --product-id contoso-product --service-name apim-hello-world --output table
   

È possibile rimuovere un'API da un prodotto usando il comando az apim product api delete:

az apim product api delete --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --product-id contoso-product \
    --service-name apim-hello-world

Accesso alle API del prodotto

Dopo aver pubblicato un prodotto, gli sviluppatori possono accedere alle API. A seconda della configurazione del prodotto, potrebbe essere necessario sottoscrivere il prodotto per l'accesso.

• Prodotto protetto: gli sviluppatori devono prima sottoscrivere un prodotto protetto per ottenere l'accesso alle API del prodotto. Quando sottoscrivono, ottengono una chiave di sottoscrizione che può accedere a qualsiasi API in tale prodotto. Se si è creata l'istanza di Gestione API, si è già un amministratore e la sottoscrizione a ogni prodotto è stata effettuata per impostazione predefinita. Per altre informazioni, vedere Sottoscrizioni in Gestione API di Azure.

  Quando un client effettua una richiesta API con un codice Product Subscription Key valido, Gestione API elabora la richiesta e consente l'accesso nel contesto del prodotto. È possibile applicare criteri e regole di controllo di accesso configurati per il prodotto.

  Suggerimento

  È possibile creare o aggiornare la sottoscrizione utente di un prodotto con chiavi di sottoscrizione personalizzate tramite l'API REST o un comando PowerShell.

• Prodotto aperto: gli sviluppatori possono accedere alle API di un prodotto aperto senza una chiave di sottoscrizione. Tuttavia, è possibile configurare altri meccanismi per proteggere l'accesso client alle API, tra cui OAuth 2.0, certificati client e limitare gli indirizzi IP del chiamante.

  Nota

  I prodotti aperti non sono elencati nel portale per sviluppatori, in modo che questi ultimi possano conoscerli o sottoscriverli. Sono visibili solo al gruppo Amministratori. È necessario usare un altro meccanismo per informare gli sviluppatori riguardo alle API a cui è possibile accedere senza una chiave di sottoscrizione.

  Quando un client effettua una richiesta API senza una chiave di sottoscrizione:

  • Gestione API controlla se l'API è associata a un prodotto aperto. Un'API può essere associata alla maggior parte di un prodotto aperto.

  • Se il prodotto aperto esiste, elabora la richiesta nel contesto del prodotto aperto. È possibile applicare criteri e regole di controllo di accesso configurati per il prodotto aperto.

Per altre informazioni, vedere Come Gestione API gestisce le richieste con o senza chiavi di sottoscrizione.

Passaggi successivi

Questa esercitazione ha descritto come:

• Creare e pubblicare un prodotto
• Aggiungere un'API al prodotto
• Accedere alle API del prodotto

Passare all'esercitazione successiva:

Creare un'API vuota e simulare le risposte di un'API