Condividi tramite

Esercitazione: Creare e pubblicare un prodotto

  • Articolo

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

Prodotti di Gestione API nel portale

Prerequisiti

Creare e pubblicare un prodotto

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

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

    Aggiungere un prodotto nel portale di Azure

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

    Finestra Aggiungi 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 nel portale per sviluppatori. Prima che le API in un prodotto possano essere individuate dagli sviluppatori, il prodotto deve essere pubblicato. Per impostazione predefinita, i nuovi prodotti non vengono pubblicati.
    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.

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

  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.

Aggiungere un'API a un prodotto esistente

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

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.

  • Specificare la versione richiesta di Terraform e i provider necessari.
  • Definire le variabili per il prefisso del nome del gruppo di risorse, la posizione del gruppo di risorse e il formato e il valore del contenuto per l'importazione della definizione API.
  • Creare un gruppo di risorse con un nome casuale.
  • Creare un servizio Gestione API con un nome casuale.
  • Creare un'API con un nome casuale.
  • Creare un prodotto con un nome casuale nel servizio Gestione API.
  • Creare un gruppo con un nome casuale.
  • Associare l'API al prodotto.
  • Associare il gruppo al prodotto.
  • Restituire i valori casuali, ad esempio i nomi del gruppo di risorse, il servizio Gestione API, l'API, il prodotto e il gruppo.

Prerequisiti

Implementare il codice Terraform

Nota

Il codice di esempio per questo articolo si trova nel repository GitHub di Azure Terraform. È possibile visualizzare il file di log contenente i risultati del test delle versioni correnti e precedenti di Terraform.

Vedere altri articoli e codici di esempio che illustrano come usare Terraform per gestire le risorse di Azure.

  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     = "http://conferenceapi.azurewebsites.net/?format=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

Creare un'API vuota e risposte API fittizie.