Esercitazione: Creare e pubblicare un prodotto

In questa esercitazione apprenderai a:

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

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

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

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:

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

az apim product api delete --resource-group apim-hello-word-resource-group \
    --api-id petstore-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:

Passare all'esercitazione successiva:

In questo articolo viene usato Terraform per creare un'istanza di Azure Gestione API, un'API, un prodotto, un gruppo e le associazioni tra il prodotto e l'API e il prodotto e il gruppo.

Terraform consente di definire, visualizzare in anteprima e distribuire l'infrastruttura cloud. Con Terraform è possibile creare file di configurazione usando la sintassi HCL. La sintassi HCL consente di specificare il provider di servizi cloud, ad esempio Azure, e gli elementi che costituiscono l'infrastruttura cloud. Dopo aver creato i file di configurazione, è necessario creare un piano di esecuzione che consenta di visualizzare in anteprima le modifiche apportate all'infrastruttura prima che vengano distribuite. Dopo aver verificato le modifiche, è possibile applicare il piano di esecuzione per distribuire l'infrastruttura.

Prerequisiti

• Creare un account Azure con una sottoscrizione attiva. È possibile creare un account gratuito.

• Installa e configura Terraform.

Implementare il codice Terraform

1. Creare una directory in cui testare ed eseguire il codice Terraform di esempio e impostarla come directory corrente.

2. Creare un file denominato main.tfe inserire il codice seguente:

   resource "random_pet" "rg_name" {
     prefix = var.resource_group_name_prefix
   }
   
   resource "azurerm_resource_group" "rg" {
     location = var.resource_group_location
     name     = random_pet.rg_name.id
   }
   
   resource "random_string" "apim_service_name" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "azurerm_api_management" "apim_service" {
     name                = "${random_string.apim_service_name.result}-apim-service"
     location            = azurerm_resource_group.rg.location
     resource_group_name = azurerm_resource_group.rg.name
     publisher_name      = "Example Publisher"
     publisher_email     = "publisher@example.com"
     sku_name            = "Developer_1"
     tags = {
       Environment = "Example"
     }
     policy {
       xml_content = <<XML
       <policies>
         <inbound />
         <backend />
         <outbound />
         <on-error />
       </policies>
   XML
     }
   }
   
   resource "random_string" "api_name" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "random_string" "content_value" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "azurerm_api_management_api" "api" {
     name                = "${random_string.api_name.result}-api"
     resource_group_name = azurerm_resource_group.rg.name
     api_management_name = azurerm_api_management.apim_service.name
     revision            = "1"
     display_name        = "${random_string.api_name.result}-api"
     path                = "example"
     protocols           = ["https", "http"]
     description         = "An example API"
     import {
       content_format = var.open_api_spec_content_format
       content_value  = var.open_api_spec_content_value
     }
   }
   
   resource "random_string" "product_name" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "azurerm_api_management_product" "product" {
     product_id            = "${random_string.product_name.result}-product"
     resource_group_name   = azurerm_resource_group.rg.name
     api_management_name   = azurerm_api_management.apim_service.name
     display_name          = "${random_string.product_name.result}-product"
     subscription_required = true
     approval_required     = false
     published             = true
     description           = "An example Product"
   }
   
   resource "random_string" "group_name" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "azurerm_api_management_group" "group" {
     name                = "${random_string.group_name.result}-group"
     resource_group_name = azurerm_resource_group.rg.name
     api_management_name = azurerm_api_management.apim_service.name
     display_name        = "${random_string.group_name.result}-group"
     description         = "An example group"
   }
   
   resource "azurerm_api_management_product_api" "product_api" {
     resource_group_name = azurerm_resource_group.rg.name
     api_management_name = azurerm_api_management.apim_service.name
     product_id          = azurerm_api_management_product.product.product_id
     api_name            = azurerm_api_management_api.api.name
   }
   
   resource "azurerm_api_management_product_group" "product_group" {
     resource_group_name = azurerm_resource_group.rg.name
     api_management_name = azurerm_api_management.apim_service.name
     product_id          = azurerm_api_management_product.product.product_id
     group_name          = azurerm_api_management_group.group.name
   }
   

3. Creare un file denominato outputs.tfe inserire il codice seguente:

   output "resource_group_name" {
     value = azurerm_resource_group.rg.name
   }
   
   output "apim_service_name" {
     value = azurerm_api_management.apim_service.name
   }
   
   output "api_name" {
     value = azurerm_api_management_api.api.name
   }
   
   output "product_name" {
     value = azurerm_api_management_product.product.product_id
   }
   
   output "group_name" {
     value = azurerm_api_management_group.group.name
   }
   
   output "service_id" {
     description = "The ID of the API Management Service created"
     value       = azurerm_api_management.apim_service.id
   }
   
   output "gateway_url" {
     description = "The URL of the Gateway for the API Management Service"
     value       = azurerm_api_management.apim_service.gateway_url
   }
   
   output "service_public_ip_addresses" {
     description = "The Public IP addresses of the API Management Service"
     value       = azurerm_api_management.apim_service.public_ip_addresses
   }
   
   output "api_outputs" {
     description = "The IDs, state, and version outputs of the APIs created"
     value = {
       id             = azurerm_api_management_api.api.id
       is_current     = azurerm_api_management_api.api.is_current
       is_online      = azurerm_api_management_api.api.is_online
       version        = azurerm_api_management_api.api.version
       version_set_id = azurerm_api_management_api.api.version_set_id
     }
   }
   
   output "product_id" {
     description = "The ID of the Product created"
     value       = azurerm_api_management_product.product.id
   }
   
   output "product_api_id" {
     description = "The ID of the Product/API association created"
     value       = azurerm_api_management_product_api.product_api.id
   }
   
   output "product_group_id" {
     description = "The ID of the Product/Group association created"
     value       = azurerm_api_management_product_group.product_group.id
   }
   

4. Creare un file denominato providers.tfe inserire il codice seguente:

   terraform {
     required_version = ">=1.0"
     
     required_providers {
       azurerm = {
         source  = "hashicorp/azurerm"
         version = "~>3.0"
       }
       random = {
         source  = "hashicorp/random"
         version = "~>3.0"
       }
     }
   }
   
   provider "azurerm" {
     features {}
   }
   

5. Creare un file denominato variables.tfe inserire il codice seguente:

   variable "resource_group_name_prefix" {
     type        = string
     default     = "rg"
     description = "Prefix of the resource group name that's combined with a random ID so name is unique in your Azure subscription."
   }
   
   variable "resource_group_location" {
     type        = string
     default     = "eastus"
     description = "Location of the resource group."
   }
   
   variable "open_api_spec_content_format" {
     type        = string
     default     = "swagger-link-json"
     description = "The format of the content from which the API Definition should be imported. Possible values are: openapi, openapi+json, openapi+json-link, openapi-link, swagger-json, swagger-link-json, wadl-link-json, wadl-xml, wsdl and wsdl-link."
     validation {
       condition     = contains(["openapi", "openapi+json", "openapi+json-link", "openapi-link", "swagger-json", "swagger-link-json", "wadl-link-json", "wadl-xml", "wsdl", "wsdl-link"], var.open_api_spec_content_format)
       error_message = "open_api_spec_content_format must be one of the following: openapi, openapi+json, openapi+json-link, openapi-link, swagger-json, swagger-link-json, wadl-link-json, wadl-xml, wsdl and wsdl-link."
     }
   }
   
   variable "open_api_spec_content_value" {
     type        = string
     default     = "https://petstore3.swagger.io/api/v3/openapi.json"
     description = "The Content from which the API Definition should be imported. When a content_format of *-link-* is specified this must be a URL, otherwise this must be defined inline."
   }
   

Inizializzare Terraform

Per inizializzare la distribuzione di Terraform, eseguire terraform init. Questo comando scarica il provider di Azure necessario per gestire le risorse di Azure.

terraform init -upgrade

Punti principali:

• Il parametro -upgrade aggiorna i plug-in del provider necessari alla versione più recente conforme ai vincoli di versione della configurazione.

Creare un piano di esecuzione Terraform

Eseguire terraform plan per creare un piano di esecuzione.

terraform plan -out main.tfplan

Punti principali:

• Il comando terraform plan consente di creare un piano di esecuzione, ma non di eseguirlo. Determina invece le azioni necessarie per creare la configurazione specificata nei file di configurazione. Questo modello consente di verificare se il piano di esecuzione corrisponde alle aspettative prima di apportare modifiche alle risorse effettive.
• Il parametro -out facoltativo consente di specificare un file di output per il piano. L'uso del parametro -out garantisce che il piano esaminato sia esattamente quello che viene applicato.

Applicare un piano di esecuzione Terraform

Eseguire terraform apply per applicare il piano di esecuzione all'infrastruttura cloud.

terraform apply main.tfplan

Punti principali:

• Il comando terraform apply di esempio presuppone che in precedenza sia stato eseguito terraform plan -out main.tfplan.
• Se è stato specificato un nome file diverso per il parametro -out, usare lo stesso nome file nella chiamata a terraform apply.
• Se non è stato usato il parametro -out, chiamare terraform apply senza parametri.

Verificare i risultati

Eseguire az apim show per visualizzare l'Gestione API di Azure:

az apim show --<apim_service_name> --<resource_group_name>

Pulire le risorse

Quando le risorse create tramite Terraform non sono più necessarie, eseguire i passaggi seguenti:

1. Eseguire terraform plan e specificare il flag destroy.

   terraform plan -destroy -out main.destroy.tfplan
   

   Punti principali:

   • Il comando terraform plan consente di creare un piano di esecuzione, ma non di eseguirlo. Determina invece le azioni necessarie per creare la configurazione specificata nei file di configurazione. Questo modello consente di verificare se il piano di esecuzione corrisponde alle aspettative prima di apportare modifiche alle risorse effettive.
   • Il parametro -out facoltativo consente di specificare un file di output per il piano. L'uso del parametro -out garantisce che il piano esaminato sia esattamente quello che viene applicato.

2. Eseguire terraform apply per applicare il piano di esecuzione.

   terraform apply main.destroy.tfplan
   

Risolvere i problemi di Terraform in Azure

Risolvere i problemi comuni relativi all'uso di Terraform in Azure.

Passaggi successivi