Come aggiungere operazioni a un'API in Gestione API di Azure

Prima di poter usare un'API in Gestione API, è necessario aggiungervi le operazioni. Questa guida descrive come aggiungere e configurare diversi tipi di operazioni a un'API in Gestione API.

Aggiungere un'operazione

Le operazioni vengono aggiunte e configurate in un'API nel portale di pubblicazione. Per accedere al portale di pubblicazione, fare clic su Portale di pubblicazione nel portale di Azure per il servizio Gestione API.

Portale di pubblicazione

Se non è stata creata un'istanza del servizio Gestione API, vedere Creare un'istanza di Gestione API nell'esercitazione Introduzione a Gestione API di Azure.

Selezionare l'API desiderata nel portale di pubblicazione e quindi selezionare la scheda Operazioni .

Operazioni

Fare clic su Aggiungi operazione per aggiungere una nuova operazione. Verrà visualizzata la finestra Nuova operazione in cui la scheda Firma è visualizzata per impostazione predefinita.

Aggiungi operazione

Specificare il verbo HTTP dall'elenco a discesa.

Metodo HTTP

Definire il modello di URL digitando un frammento dell'URL composto da uno o più segmenti di percorso dell'URL e zero o più parametri di stringa di query. Il modello di URL, aggiunto all'URL di base dell'API, identifica una singola operazione HTTP. Può contenere una o più parti variabili denominate identificate da parentesi graffe. Queste parti variabili sono denominate parametri di modello e ad esse vengono assegnati in modo dinamico i valori estratti dall'URL della richiesta quando la richiesta viene elaborata dalla piattaforma di Gestione API.

Il modello di URL può includere caratteri jolly. Specificando ad esempio /*, tutte le richieste per il metodo HTTP verranno inoltrate al servizio back-end.

Modello di URL

Se si vuole, è possibile specificare il Modello di URL di riscrittura. Questo consente di usare il modello di URL standard per elaborare le richieste in ingresso nel front-end, chiamando il back-end tramite un URL convertito in base al modello di riscrittura. Nel modello di riscrittura è necessario usare i parametri di modello dell'URL di modello. L'esempio seguente mostra il modo in cui il tipo di contenuto codificato come segmento del percorso nel servizio Web dell'esempio precedente può essere specificato come parametro di query nell'API pubblicata tramite la piattaforma di Gestione API usando i modelli di URL.

Riscrittura modello di URL

I chiamanti delle operazioni useranno il formato /customers?customerid=ALFKI che verrà mappato a /Customers('ALFKI') quando viene richiamato il servizio back-end.

In Nome visualizzato e Descrizione viene fornita una descrizione dell'operazione e vengono usati per fornire la documentazione necessaria agli sviluppatori che usano questa API nel portale per sviluppatori.

Description

È possibile specificare la descrizione dell'operazione come testo normale o HTML nella casella di testo Descrizione .

Memorizzazione nella cache di un'operazione

La memorizzazione nella cache della risposta riduce la latenza percepita dai consumer dell'API, riduce l'utilizzo della larghezza di banda e diminuisce il carico nel servizio Web HTTP che implementa l'API.

Per abilitare la memorizzazione nella cache per l'operazione in modo facile e veloce, selezionare la scheda Memorizzazione nella cache e selezionare la casella di controllo Abilita.

Memorizzazione nella cache

Durata viene specificato il periodo di tempo durante il quale la risposta dell'operazione rimane nella cache. Il valore predefinito è 3.600 secondi o un'ora.

Le chiavi della cache vengono usate per differenziare le risposte in modo che ogni risposta corrispondente a una chiave della cache ottenga il proprio valore memorizzato nella cache separato. Facoltativamente, è possibile immettere parametri di stringa di query specifici e/o intestazioni HTTP da usare nei valori delle chiavi della cache di calcolo rispettivamente nelle caselle di testo Varia in base ai parametri di stringa di query e Varia in base alle intestazioni. Se non viene specificato alcun valore, per la generazione della chiave della cache vengono usati i valori dell'URL di richiesta completo e l'intestazione HTTP seguenti: Accept e Accept-Charset.

Per altre informazioni sulla memorizzazione nella cache e sui relativi criteri, vedere Come memorizzare nella cache i risultati dell'operazione in Gestione API di Azure.

Parametri della richiesta

È possibile gestire i parametri dell'operazione nella scheda Parametri. I parametri specificati in Modello di URL nella scheda Firma vengono aggiunti automaticamente e possono essere cambiati solo modificando il modello di URL. È possibile immettere i parametri aggiuntivi manualmente.

Per aggiungere un parametro di query, fare clic su Aggiungi parametro di query e immettere le informazioni seguenti:

  • Nome : nome del parametro.
  • Descrizione : breve descrizione del parametro (facoltativa).
  • Tipo : tipo del parametro, selezionato nell'elenco a discesa.
  • Valori : valori che possono essere assegnati al parametro. Uno dei valori può essere contrassegnato come predefinito (facoltativo).
  • Obbligatorio : selezionare questa casella di controllo per rendere il parametro obbligatorio.

Parametri della richiesta

Corpo della richiesta

Se l'operazione consente (ad esempio, PUT, POST) e richiede un corpo, è possibile fornirne un esempio in tutti i formati di rappresentazione supportati, ad esempio JSON e XML.

Il corpo della richiesta è usato solo ai fini della documentazione e non viene convalidato.

Per immettere un corpo della richiesta, passare alla scheda Corpo .

Fare clic su Aggiungi rappresentazione, iniziare a digitare il nome del tipo di contenuto desiderato (ad esempio, applicazione/json), selezionarlo nell'elenco a discesa e incollare nella casella di testo l'esempio di corpo della richiesta nel formato selezionato.

Corpo della richiesta

Oltre alle rappresentazioni, è possibile specificare una descrizione di testo facoltativa nella casella di testo Descrizione .

Risposte

È consigliabile fornire esempi di risposte per tutti i codici di stato restituiti dall'operazione. Per ogni codice di stato può esistere più di un esempio di corpo della risposta, ovvero uno per ogni tipo di contenuto supportato.

Per aggiungere una risposta, fare clic su Aggiungi e iniziare a digitare il codice di stato desiderato. In questo esempio il codice di stato è 200 OK. Quando il codice viene visualizzato nell'elenco a discesa, selezionarlo in modo che il codice della risposta venga creato e aggiunto all'operazione.

Codice della risposta

Fare clic su Aggiungi rappresentazione, iniziare a digitare il nome del tipo di contenuto desiderato (ad esempio, applicazione/json) e selezionarlo nell'elenco a discesa.

Tipo di contenuto del corpo

Incollare nella casella di testo l'esempio del corpo della risposta nel formato selezionato.

Corpo della risposta

Se necessario, aggiungere una descrizione facoltativa nella casella di testo Descrizione .

Dopo avere configurato l'operazione, fare clic su Salva.

Passaggi successivi

Una volta aggiunte le operazioni a un'API, nel passaggio successivo l'API verrà associata a un prodotto e verrà pubblicata in modo che gli sviluppatori possano chiamare le relative operazioni.