Attività iniziali per il Centro API

Completato

In questo esercizio si eseguiranno le seguenti operazioni:

1. Creare un servizio Centro API.

2. Definire le proprietà dei metadati.

3. Aggiungere le API al Centro API.

4. Aggiungere distribuzioni e ambienti.

Prerequisiti

Per iniziare a gestire le API tramite il Centro API, è necessario:

1. Una sottoscrizione di Azure.
2. Provider di risorse Microsoft.ApiCenter registrato nella sottoscrizione.
3. Nella sottoscrizione di Azure deve esistere almeno un'assegnazione di ruolo Collaboratore o autorizzazioni equivalenti.

Nota

Se non è stato già fatto, registrare il provider di risorse Microsoft.ApiCenter nella sottoscrizione.

1. Accedere al portale di Azure.
2. Immettere Sottoscrizioni nella barra di ricerca.
3. Selezionare la sottoscrizione in cui si vuole creare il Centro API.
4. Nel menu a sinistra, da Risorse, selezionare Provider di risorse.
5. Cercare Microsoft.ApiCenter nell'elenco dei provider di risorse. Se non è registrato, selezionare Registra.

Passaggio 1: Creare un servizio Centro API

1. Accedere al portale di Azure.

2. Nella barra di ricerca immettere Centri API.

3. Seleziona + Crea.

4. Nella scheda Informazioni di base seleziona o immetti le impostazioni seguenti:

   a. Seleziona la tua sottoscrizione di Azure.

   b. Selezionare un gruppo di risorse esistente oppure scegliere Nuovo per crearne uno nuovo.

   c. Immetti un Nome per il centro API. Deve essere univoco nella regione in cui stai creando il centro API.

   d. InArea, selezionare una delle aree disponibili per Centro API.

   e. Per il piano tariffario, selezionare Versione di valutazione gratuita ($0 per 90 giorni).

   f. Selezionare Rivedi e crea.

   h. Al termine della convalida selezionare Crea.

   Dopo la distribuzione, il centro API è pronto per l'uso.

Per eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure ed eseguire l'accesso con il comando seguente.

az login

Nota

Se non è stato già fatto, registrare il provider di risorse Microsoft.ApiCenter nella sottoscrizione.

Eseguire il comando seguente per registrare il provider di risorse

az provider register –namespace Microsoft.ApiCenter 

Passaggio 1: Creare un servizio Centro API

Creare un gruppo di risorse eseguendo il comando seguente e passando:

• Nome del gruppo di risorse --name Esempio: Contoso
• Percorso --location Esempio: Stati Uniti orientali

az group create –-name contoso –-location eastus  

Nota

I comandi az apic richiedono l'estensione dell'interfaccia della riga di comando di Azure apic-extension. Se non sono stati usati i comandi az apic, l'estensione verrà installata in modo dinamico quando si esegue il primo comando az apic oppure è possibile installare l'estensione manualmente. Altre informazioni sulle estensioni dell'interfaccia della riga di comando di Azure.

Creare un Centro API eseguendo il comando seguente, passando:

• Nome del servizio Centro API -n Esempio: contoso-apis
• Gruppo di risorse -g Esempio: Contoso
• Percorso --l Esempio: Stati Uniti orientali

az apic create -n contoso-apis -g contoso -l eastus 

Nota

Per impostazione predefinita, il Centro API sarà creato con piano tariffario Gratuito.

Nota

La creazione di un servizio del Centro API non è attualmente supportata in Visual Studio Code. Crearne una usando l'interfaccia della riga di comando di Azure o il portale di Azure.

Passaggio 2: Definire le proprietà dei metadati

Il Centro API usa le proprietà dei metadati per organizzare le API nell'inventario e quindi abilitare operazioni come il filtro, la ricerca e così via.

Nota

Nei titoli/nomi delle proprietà dei metadati, non includere informazioni riservate, riservate o personali.

Contoso, come molte altre organizzazioni, desidera che tutte le API passino attraverso un responsabile approvazione prima di diventare disponibili per l'uso, e assicurare che per tutte le API venga eseguita una verifica di conformità. L'organizzazione inoltre dispone di API pubbliche e altre create esclusivamente per uso interno. Per applicare questa operazione su larga scala per tutte le API, vengono aggiunte tre proprietà di metadati personalizzate:

• Responsabile approvazione API di tipo Stringa
• Verifica della conformità di tipo Scelte predefinite
• Pubblico di tipo Booleano

1. Nel menu a sinistra, selezionare Asset Metadati > > + Nuovi metadati.

2. Nella scheda Dettagli immettere le informazioni sulla proprietà.

   a. In Titolo, immettere responsabile approvazione API

   b. In Descrizioneimmettere responsabile approvazione API predefinita

   c. Selezionare il tipo Stringa, quindi selezionare Avanti

3. Nella scheda Assegnazioni, selezionare Obbligatorio per le API. Selezionare Facoltativo per Distribuzioni e Ambienti. Selezionare Avanti.

4. Selezionare Crea.

5. Ripetere gli stessi passaggi per la proprietà Pubblico, come mostrato nell'immagine seguente. Per tipo, selezionare Booleano

6. Nella scheda Assegnazioni, selezionare Obbligatorio per le API. Selezionare Non applicabile per Distribuzioni e Ambienti. Selezionare Avanti.

7. Selezionare Crea.

8. Ripetere gli stessi passaggi per la proprietà Revisione-conformità, come mostrato nell'immagine seguente. Per il tipo, selezionare opzioni predefinite e aggiungere 3 opzioni: Non avviato, In corso e Completato

9. Nella scheda Assegnazioni, selezionare Obbligatorio per le API. Selezionare Non applicabile per Distribuzioni e Ambienti

10. Selezionare Avanti.

Adesso è disponibile uno schema di metadati JSON per le API, disponibili per la visualizzazione, la modifica e il download. Per visualizzare, selezionare Visualizza schema dei metadati, quindi selezionare API nell'elenco a discesa.

Si apre una finestra modale a destra con i dettagli dei metadati, che includono le proprietà predefinite del Centro API, ad esempio, tra le altre: LifecycleStage,Nome, Descrizione, TermsOfService. Se si scorre fino alla fine del file, saranno visualizzati i metadati personalizzati aggiunti nei passaggi precedenti, come mostrato di seguito.

Nota

In qualsiasi momento è possibile aggiungere e modificare le proprietà nello schema, e quindi applicarle immediatamente a tutte le API nel Centro API

Creare un nuovo schema di metadati eseguendo il comando seguente per impostare:

• Metadati nome come api-approver
• Schema con tipo di proprietà come Stringa e titolo come Responsabile approvazione API
• Assegnazioni come necessarie per le API, come facoltative per Ambiente e Distribuzione

az apic metadata create -g contoso -n contoso-apis --metadata-name "api-approver" --schema '{"type":"string","title":"API Approver"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

Ripetere gli stessi passaggi per:

• Metadati nome come pubblico
• Schema con tipo di proprietà booleano e titolo come pubblico
• Assegnazioni come necessarie per le API, come facoltative per Ambiente e Distribuzione

Eseguendo questo comando:

az apic metadata create -g contoso -n contoso-apis --metadata-name "public-facing" --schema '{"type":"boolean", "title":"Public Facing"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

Infine, ripetere gli stessi passaggi per:

• Metadati nome come verifica della conformità
• Schema con tipo di proprietà come Stringa e titolo come Verifica della conformità
• Assegnazioni come necessarie per le API, come facoltative per Ambiente e Distribuzione

Eseguendo questo comando:

az apic metadata create -g contoso -n contoso-apis --metadata-name "compliance-review" --schema '{"type":"string","title":"Compliance Review", "oneOf":[{"const":"Not Started","description":""},{"const":"In Progress","description":""},{"const":"Completed","description":""}]}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

È possibile eseguire il comando seguente per visualizzare un elenco di tutti i metadati definiti nel Centro API.

az apic metadata list -g <resource-group-name> -n <api-center-name> 

Nota

In qualsiasi momento è possibile aggiungere e modificare le proprietà nello schema, e quindi applicarle immediatamente a tutte le API nel Centro API

Nota

Questa azione non è attualmente supportata in Visual Studio Code. Crearne una usando l'interfaccia della riga di comando di Azure o il portale di Azure.

Passaggio 3: Aggiungere le API all'inventario

Per i team di progettazione, l'organizzazione Contoso preferisce le conferenze tecniche, nell'ambito delle competenze interne. Sarà aggiunta una Conferenza API con relatori, sessioni e argomenti.

URL di Conferenza API: https://bigconference.azurewebsites.net/

Per i passaggi seguenti, è possibile copiare la definizione OpenAPI dal sito Web di cui sopra e salvarla come file JSON nel computer locale. Alternativamente, sostituire una definizione API diversa quando si aggiunge un'API all'inventario.

1. Nel portale, passare al proprio centro API.

2. Nel menu a sinistra selezionare Risorse > API > + Registra API.

3. Nella pagina Registra API aggiungere le informazioni seguenti necessarie per l'API. Nella parte inferiore della pagina verranno visualizzate le proprietà personalizzate dei metadati del Responsabile approvazione dell'API, *pubblico e verifica conformità definite nei passaggi precedenti.

Per visualizzare l'API creata, nel menu a sinistra, selezionare Risorse> API > Conferenza API.

La scheda Panoramica offre la visualizzazione della configurazione dell'API. Espandere Dettagli per visualizzare e modificare informazioni aggiuntive, ad esempio la versione dell'API e le distribuzioni (ora non sono disponibili distribuzioni).

In genere, è consigliabile aggiungere una definizione API per la versione dell'API. Il Centro API supporta i formati di specifica del testo, tra cui OpenAPI 2 e OpenAPI 3 per REST.

Per aggiungere una definizione,

1. Nel menu a sinistra selezionare Asset > API > Selezionare l'API (Conferenza API).
2. Espandere Dettagli, quindi selezionare Versioni.
3. Selezionare la versione (v1), ed espandere Dettagli.
4. In dettagli, selezionare Definizioni >Aggiungi definizione.

Per registrare un'API nell'istanza dell'API, è possibile usare Estensione Centro API di Azure per Visual Studio Code.

Passaggio 1: Installare l'estensione

Passaggio 2: Aprire il riquadro comandi, ‘CTRL + MAIUSC + P’ e digitare Centro API: Registrare l'API

Seguire le richieste per specificare le informazioni seguenti per l’API:

Registrare l'API	Procedura dettagliata
Selezionare Servizio Centro API	Selezionare l'istanza Centro API
Titolo API	Immettere il nome dell'API (Conferenza API)
Tipo di API	REST
Titolo versione API	Immettere un nome per la versione per l'API (v1)
Ciclo di vita della versione API	Selezionare un ciclo di vita dall'elenco a discesa (Sviluppo)
Titolo definizione API	Immettere un nome per la definizione (Definizione Conferenza API)
Nome specifica API	Scegliere una specifica nell'elenco a discesa (OpenAPI 2)
Selezionare File di definizione API da importare	Esplorare e selezionare il file di definizione dalla risorsa di archiviazione

Aggiornare la scheda di estensione del Centro API. L'API appena creata viene visualizzata nella rispettiva istanza/risorsa APIC.

Usare il comando seguente per creare una nuova API, passando in:

• Gruppo di risorse -g Esempio: Contoso
• Nome del servizio Centro API -n Esempio: contoso-api-center
• Titolo --title Esempio: Conferenza API
• ID API --api-id Esempio: conference-api
• Tipo --type Esempio: REST

az apic api create -g contoso -n contoso-apis --title "Conference API" --api-id conference-api --type REST

Creare una versione API usando il comando seguente, passando in:

• Gruppo di risorse -g Esempio: contoso
• Nome del servizio Centro API -n Esempio: contoso-apis
• ID API --api-id Esempio: conference-api
• Titolo --title Esempio: v1.2.2
• ID versione --version-id Esempio: 03-07-2024
• Fase del ciclo di vita --lifecycle-stage Esempio: progettazione

az apic api version create -g contoso -n contoso-apis --api-id conference-api --title v1.2.2 --version-id 2024-07-03 --lifecycle-stage design

Inoltre è possibile aggiungere una definizione API per la versione dell'API e il Centro API supporta i formati di specifica del testo, tra cui OpenAPI 2 e OpenAPI 3 per REST.

Per aggiungere una definizione, usare il comando seguente, passando in:

• Gruppo di risorse -g Esempio: contoso
• Nome del servizio Centro API -n Esempio: contoso-apis
• ID API --api-id Esempio: conference-api
• ID versione --version-id Esempio: 03-07-2024
• Titolo --title Esempio: OpenAPI
• ID definizione--definition-id Esempio: openapi

az apic api definition create -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --title OpenAPI --definition-id openapi 

Per importare un file di definizione OpenAPI da un URL, usare il comando definizione di specifica importazione az apic api. Esempio: https://learn.microsoft.com/cli/azure/apic/api/definition?view=azure-cli-latest#az-apic-api-definition-import-specification-examples

az apic api definition import-specification -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --definition-id openapi --format "link" --value 'https://petstore3.swagger.io/api/v3/openapi.json' --specification '{"name":"openapi","version":"3.0.2"}'

Passaggio 4: Aggiungere distribuzioni e ambienti

Ambienti

Un ambiente (sviluppo, test, gestione temporanea o produzione) rappresenta un percorso in cui è distribuito un runtime API. I tecnici della piattaforma per API di Contoso definiscono due ambienti: test e produzione, per gestire e tenere traccia dei diversi runtime API nell'organizzazione.

Per creare un ambiente:

1. Nel menu a sinistra selezionare Risorse > Ambienti > + Nuovo ambiente.

2. Aggiungi le seguenti informazioni.

3. Seleziona Crea.

4. Ripetere gli stessi passaggi per Ambiente di produzione.

   

Per creare un ambiente, eseguire il comando dell'interfaccia della riga di comando seguente

az apic environment create -g contoso -n contoso-apis --title ContosoTesting --environment-id contosotesting --type testing

Ripetere gli stessi passaggi per l’ambiente di produzione

az apic environment create -g contoso -n contoso-apis-new --title ContosoProduction --environment-id contosoproduction --type production

Nota

La creazione di ambienti non è attualmente supportata in Visual Studio Code. Usare l'interfaccia della riga di comando di Azure o l'opzione del portale di Azure per eseguire questo passaggio.

Deployments

Viene fornita una posizione univoca (indirizzo) per gli utenti che interagiscono con l'API, per ciascun runtime API in un determinato ambiente. Questo percorso è definito distribuzione, e una singola versione API può avere due distribuzioni: una gestione temporanea e una distribuzione di produzione.

Contoso ha un'API, Conferenza API, che viene associata agli ambienti creati.

1. Nel portale, passare al proprio centro API.

2. Nel menu a sinistra selezionare API, quindi selezionare un'API: ad esempio Conferenza API.

3. Nella pagina Conferenza API, espandere Dettagli Distribuzioni > >+ Aggiungi distribuzione.

4. Aggiungere le informazioni seguenti:

   a. Selezionare Test Contoso nell'elenco a discesa per il campo Ambiente.

   b. Per la definizione fare clic su Seleziona, scegliere la versione API v1nell'elenco a discesa e selezionare la definizione aggiunta in precedenza. Fare clic su Seleziona.

   c. Dopo aver aggiunto correttamente la definizione, aggiungere un URL di runtime di base, il quale sarà specifico per l'API nell'ambiente selezionato.

   

Per creare una distribuzione e associarla all'ambiente creato nel passaggio precedente, eseguire il comando dell'interfaccia della riga di comando seguente

az apic api deployment create -g contoso-corporation -s contoso-api-center --deployment-id "v1-conference-api" --title "Conference OpenAPI 2" --description "Conference Demo API deployment." --api-id conference-api --environment-id "/workspaces/default/environments/contoso-testing" --definition-id "/workspaces/default/apis/conference-api/versions/v1/definitions/conference-openapi-2" --server '{"runtimeUri":["https://conferenceapi.azurewebsites.net/"]}'

Nota

La creazione di distribuzioni non è attualmente supportata in Visual Studio Code. Usare l'interfaccia della riga di comando di Azure o l'opzione del portale di Azure per eseguire questo passaggio.