Come salvare e configurare la configurazione del servizio Gestione API tramite Git

Articolo
03/19/2024

SI APPLICA A: Sviluppatore | Basic | Standard | Premium

Ogni istanza del servizio Gestione API gestisce un database di configurazione che contiene informazioni sulla configurazione e i metadati dell'istanza del servizio. Per apportare modifiche all'istanza del servizio, è possibile modificare un'impostazione nel portale di Azure, usare un cmdlet di PowerShell o l’interfaccia della riga di comando di Azure, o eseguire una chiamata all'API REST. Oltre a questi metodi, è possibile gestire la configurazione dell'istanza del servizio tramite Git. Ciò consente scenari di gestione del servizio diversi, ad esempio:

Controllo delle versioni della configurazione - Scaricare e archiviare versioni diverse della configurazione del servizio
Modifiche alla configurazione in blocco - Apportare modifiche a più parti della configurazione del servizio nel repository locale e integrare le modifiche al server con una singola operazione
Serie di strumenti e flussi di lavoro Git familiari: possibilità di usare gli strumenti e i flussi di lavoro Git con cui si ha familiarità

Il diagramma seguente offre una panoramica dei diversi modi in cui è possibile configurare un'istanza del servizio Gestione API.

Diagramma che confronta i modi per configurare Gestione API di Azure.

Quando si apportano modifiche al servizio usando il portale di Azure, gli strumenti di Azure, ad esempio Azure PowerShell o l'interfaccia della riga di comando di Azure o l'API REST, si gestisce il database di configurazione del servizio usando l'endpoint https://{name}.management.azure-api.net, come illustrato sul lato destro del diagramma. Il lato sinistro del diagramma illustra come gestire la configurazione del servizio tramite Git e il repository Git per il servizio, disponibile all'indirizzo https://{name}.scm.azure-api.net.

I passaggi seguenti offrono una panoramica della gestione dell'istanza del servizio Gestione API tramite Git.

Accedere alla configurazione Git nel servizio
Salvare il database di configurazione del servizio nel repository Git
Clonare il repository Git nel computer locale
Estrarre il repository più recente nel computer locale ed eseguire il commit e il push delle modifiche nel repository
Distribuire le modifiche dal repository nel database di configurazione del servizio

Questo articolo descrive come abilitare e usare Git per gestire la configurazione del servizio e costituisce un riferimento per i file e le cartelle nel repository Git.

Importante

Questa funzionalità è progettata per funzionare con configurazioni di API Management di piccole e medie dimensioni, ad esempio quelle con dimensioni esportate inferiori a 10 MB o con meno di 10.000 entità. I servizi con un numero elevato di entità (prodotti, API, operazioni, schemi e così via) possono riscontrare errori imprevisti durante l'elaborazione dei comandi Git. Se si verificano errori di questo tipo, ridurre le dimensioni della configurazione del servizio e riprovare. Se è necessaria assistenza, contattare il supporto tecnico di Azure.

Accedere alla configurazione Git nel servizio

Accedere all'istanza di Gestione API nel portale di Azure.
Nel menu a sinistra, in Distribuzione e infrastruttura, selezionare Repository.

Screenshot che mostra come accedere alla configurazione Git per Gestione API.

Salvare la configurazione del servizio nel repository Git

Attenzione

Tutti i segreti non definiti come valori denominati verranno archiviati nel repository e rimarranno nella cronologia. I valori denominati rappresentano un luogo sicuro per gestire i valori stringa costanti, segreti inclusi, attraverso tutte le configurazioni e tutti i criteri per le API. Non è quindi necessario archiviarli direttamente nelle istruzioni dei criteri. Per altre informazioni, vedere Usare valori denominati nei criteri di Gestione API di Azure.

Prima di clonare il repository, salvare lo stato corrente della configurazione del servizio nel repository.

Nella pagina Repository selezionare Salva nel repository.
Apportare le modifiche desiderate nella schermata di conferma, ad esempio il nome del ramo per salvare la configurazione e selezionare Salva.

Dopo qualche secondo la configurazione viene salvata e viene visualizzato lo stato della configurazione del repository, con la data e l'ora dell'ultima modifica alla configurazione e l'ultima sincronizzazione tra la configurazione del servizio e il repository.

Dopo che la configurazione è stata salvata nel repository, può essere clonata.

Per informazioni sul salvataggio della configurazione del servizio tramite l'API REST, vedere Configurazione del tenant - Salvataggio.

Ottenere le credenziali di accesso

Per clonare un repository, oltre all'URL del repository, è necessario un nome utente e una password.

Nella pagina Repository selezionare Credenziali di accesso nella parte superiore della pagina.
Prendere nota del nome utente specificato nella pagina Credenziali di accesso.
Per generare una password, assicurarsi prima di tutto che il campo Expiry (Scadenza) sia impostato sulla data e l'ora di scadenza desiderate e quindi selezionare Genera.

Importante

Prendere nota della password. Una volta chiusa questa pagina, la password non verrà più visualizzata.

Clonare il repository nel computer locale

Gli esempi seguenti usano lo strumento Git Bash di Git per Windows ma è possibile usare qualsiasi strumento Git con cui si abbia familiarità.

Aprire lo strumento Git nella cartella desiderata ed eseguire il comando seguente per clonare il repository Git nel computer locale usando il comando seguente:

git clone https://{name}.scm.azure-api.net/

Specificare il nome utente e la password quando richiesto.

Se si ricevono errori, provare a modificare il comando git clone includendo il nome utente e password, come illustrato nell'esempio seguente.

git clone https://username:password@{name}.scm.azure-api.net/

Se viene generato un errore, provare a codificare con URL la parte della password del comando. Un metodo rapido per eseguire questa operazione consiste nell'aprire Visual Studio, eseguendo il comando seguente nella finestra di controllo immediato. Per aprire la finestra di controllo immediato, aprire qualsiasi soluzione o progetto in Visual Studio oppure creare una nuova applicazione console vuota e quindi Finestre e quindi Controllo immediato dal menu Debug.

?System.Net.WebUtility.UrlEncode("password from the Azure portal")

Per creare il comando git, usare la password codificata con il nome utente e il percorso del repository.

git clone https://username:url encoded password@{name}.scm.azure-api.net/

Al termine della clonazione, modificare la directory nel repository eseguendo un comando simile al seguente.

cd {name}.scm.azure-api.net/

Se la configurazione è stata salvata in un ramo diverso dal ramo predefinito (master), controllare il ramo:

git checkout <branch_name>

Dopo che il repository è stato clonato, è possibile visualizzarlo e usarlo nel file system locale. Per altre informazioni, vedere Informazioni di riferimento sulla struttura di file e cartelle del repository Git locale.

Aggiornare il repository locale con la configurazione dell'istanza del servizio più recente

Se si apportano modifiche all'istanza del servizio Gestione API nel portale di Azure o si usano altri strumenti di Azure, è necessario salvare queste modifiche nel repository prima di poter aggiornare il repository locale con le modifiche più recenti.

Per salvare le modifiche usando il portale di Azure, selezionare Salva nel repository nella scheda Repository per l'istanza di Gestione API.

Quindi, per aggiornare il repository locale:

Assicurarsi di essere nella cartella per il repository locale. Se è appena stato eseguito il comando git clone , è necessario modificare la directory con quella del repository tramite un comando simile al seguente.
```
cd {name}.scm.azure-api.net/
```
Nella cartella del repository locale eseguire il comando seguente.
```
git pull
```

Eseguire il push delle modifiche dal repository locale al repository del server

Per eseguire il push delle modifiche dal repository locale al repository del server, è prima necessario eseguire il commit delle modifiche stesse. Per eseguire il commit delle modifiche, aprire lo strumento dei comandi Git, passare alla directory del repository locale ed eseguire i comandi seguenti.

git add --all
git commit -m "Description of your changes"

Per eseguire il push di tutti i commit nel server, eseguire il comando seguente.

git push

Distribuire le modifiche alla configurazione del servizio nell'istanza del servizio Gestione API

Dopo il commit e il push delle modifiche locali nel repository del server, è possibile distribuire le modifiche all'istanza del servizio Gestione API.

Accedere all'istanza di Gestione API nel portale di Azure.
Nel menu a sinistra, in Distribuzione e infrastruttura, selezionare Repository>Distribuisci a Gestione API.
Nella pagina Distribuisci configurazione repository, immettere il nome del ramo contenente le modifiche di configurazione desiderate e, facoltativamente, selezionare Rimuovi sottoscrizioni di prodotti eliminati. Seleziona Salva.

Per informazioni sull'esecuzione di questa operazione tramite l'API REST, vedere Configurazione del tenant - Distribuzione.

Informazioni di riferimento sulla struttura di file e cartelle del repository Git locale

I file e cartelle nel repository Git locale contengono le informazioni di configurazione dell'istanza del servizio.

Articolo	Descrizione
Cartella api-management radice	Contiene la configurazione di livello superiore per l'istanza del servizio
Cartella apiReleases	Contiene la configurazione per le versioni dell'API nell'istanza del servizio
Cartella apis	Contiene la configurazione per le API nell'istanza del servizio
Cartella apiVersionSets	Contiene la configurazione per i set di versioni dell'API nell'istanza del servizio
Cartella back-end	Contiene la configurazione per le risorse back-end nell'istanza del servizio
Cartella groups	Contiene la configurazione per i gruppi nell'istanza del servizio
Cartella policies	Contiene i criteri dell'istanza del servizio
Cartella portalStyles	Contiene la configurazione delle personalizzazioni del portale per sviluppatori nell'istanza del servizio
Cartella portalTemplates	Contiene la configurazione per i modelli del portale per sviluppatori nell'istanza del servizio
Cartella products	Contiene la configurazione per i prodotti nell'istanza del servizio
Cartella templates	Contiene la configurazione per i modelli nell'istanza del servizio

Ogni cartella può contenere uno o più file e in alcuni casi una o più cartelle, ad esempio una cartella per ogni API, prodotto o gruppo. I file all'interno di ogni cartella sono specifici per il tipo di entità descritto dal nome della cartella.

Tipo di file	Scopo
JSON	Informazioni di configurazione dell'entità corrispondente
html	Descrizioni delle entità, spesso visualizzate nel portale per sviluppatori
xml	Policy statements
css	Fogli di stile per la personalizzazione del portale per sviluppatori

Questi file possono essere creati, eliminati, modificati e gestiti nel file system locale e le modifiche possono essere ridistribuite nell'istanza del servizio Gestione API.

Nota

Le entità seguenti non sono contenute nel repository Git e non possono essere configurate tramite Git.

Utenti
Sottoscrizioni
Valori denominati
Entità del portale per sviluppatori diverse da stili e modelli
Frammenti di criteri

Cartella api-management radice

La cartella api-management radice contiene un file configuration.json che a propria volta contiene informazioni di livello superiore relative all'istanza del servizio nel formato seguente.

{
  "settings": {
    "RegistrationEnabled": "True",
    "UserRegistrationTerms": null,
    "UserRegistrationTermsEnabled": "False",
    "UserRegistrationTermsConsentRequired": "False",
    "DelegationEnabled": "False",
    "DelegationUrl": "",
    "DelegatedSubscriptionEnabled": "False",
    "DelegationValidationKey": "",
    "RequireUserSigninEnabled": "false"
  },
  "$ref-policy": "api-management/policies/global.xml"
}

Le prime quattro impostazioni (RegistrationEnabled, UserRegistrationTerms, UserRegistrationTermsEnabled e UserRegistrationTermsConsentRequired) vengono mappate alle impostazioni seguenti nella scheda Identità della sezione portale per sviluppatori.

Impostazione	Esegue il mapping a
RegistrationEnabled	Presenza del provider di identità per nome utente e password
UserRegistrationTerms	Terms of use on user signup
UserRegistrationTermsEnabled	Show terms of use on signup page
UserRegistrationTermsConsentRequired	Richiedi consenso
RequireUserSigninEnabled	Redirect anonymous users to

Le quattro impostazioni successive (DelegationEnabled, DelegationUrl, DelegatedSubscriptionEnabled e DelegationValidationKey) vengono mappate alle impostazioni seguenti nella scheda delega nella sezione portale per sviluppatori.

Impostazione	Esegue il mapping a
DelegationEnabled	Casella di controllo Delegate sign-in & sign-up (Delega accesso e iscrizione)
DelegationUrl	Delegation endpoint URL
DelegatedSubscriptionEnabled	Delegate product subscription
DelegationValidationKey	Delegate Validation Key

L'impostazione finale, $ref-policy, esegue il mapping al file di istruzioni dei criteri globali per l'istanza del servizio.

Cartella apiReleases

La cartella apiReleases contiene una cartella per ogni versione dell'API distribuita in un'API di produzione e contiene gli elementi seguenti.

apiReleases\<api release Id>\configuration.json: Configurazione per la versione, contenente informazioni sulle date di rilascio. Si tratta delle stesse informazioni che verrebbero restituite se si desidera chiamare l'operazione Ottieni una versione specifica.

Cartella apis

La cartella apis contiene, per ogni API nell'istanza del servizio, una cartella contenente a sua volta gli elementi seguenti.

apis\<api name>\configuration.json: configurazione per l'API contenente informazioni sull'URL del servizio back-end e sulle operazioni. Si tratta delle stesse informazioni che verrebbero restituite se fosse necessario chiamare l'operazione Ottieni un'API specifica.
apis\<api name>\api.description.html - Descrizione dell'API, corrispondente alla proprietà description dell'entità API nell'API REST.
apis\<api name>\operations\ - cartella contenente file <operation name>.description.html di cui viene eseguito il mapping alle operazioni nell'API. Ogni file contiene la descrizione di una singola operazione dell'API che esegue il mapping alla proprietà description dell'entità relativa all'operazione nell'API REST.

Cartella apiVersionSets

La cartella apiVersionSets contiene una cartella per ogni set di versioni dell'API creato per un'API e contiene gli elementi seguenti.

apiVersionSets\<api version set Id>\configuration.json - Configurazione per il set di versioni. Si tratta delle stesse informazioni che verrebbero restituite se si desidera chiamare l'operazione Ottieni un set di versioni specifico.

Cartella groups

La cartella groups contiene una cartella per ogni gruppo definito nell'istanza del servizio.

groups\<group name>\configuration.json: Configurazione per il gruppo. Si tratta delle stesse informazioni che verrebbero restituite se fosse necessario chiamare l'operazione per ottenere un gruppo specifico .
groups\<group name>\description.html: Descrizione del gruppo, corrispondente alla proprietà description dell'entità gruppo.

Cartella policies

La cartella policies contiene le istruzioni dei criteri per l'istanza del servizio.

policies\global.xml: Criteri definiti nell'ambito globale per l'istanza del servizio.
policies\apis\<api name>\: Se sono stati definiti criteri nell'ambito dell'API, sono contenuti in questa cartella.
Cartella policies\apis\<api name>\<operation name>\: se sono presenti dei criteri nell'ambito dell'operazione, sono contenuti in questa cartella nei file <operation name>.xml che eseguono il mapping alle istruzioni dei criteri per ogni operazione.
policies\products\: se sono presenti dei criteri definiti nell'ambito dei prodotti, tali criteri sono contenuti in questa cartella, contenente file <product name>.xml mappati alle istruzioni dei criteri per ogni prodotto.

Cartella portalStyles

La cartella portalStyles contiene fogli di configurazione e stile per personalizzare il portale per sviluppatori deprecato dell'istanza del servizio.

portalStyles\configuration.json: contiene i nomi dei fogli di stile usati dal portale per sviluppatori
portalStyles\<style name>.css: ogni file <style name>.css contiene stili per il portale per sviluppatori (per impostazione predefinita, Preview.css e Production.css).

Cartella portalTemplates

La cartella portalTemplates contiene modelli per personalizzare il portale per sviluppatori deprecato dell'istanza del servizio.

portalTemplates\<template name>\configuration.json: Configurazione del modello.
portalTemplates\<template name>\<page name>.html: Pagine HTML originali e modificate del modello.

Cartella products

La cartella products contiene una cartella per ogni prodotto definito nell'istanza del servizio.

products\<product name>\configuration.json: Configurazione per il prodotto. Si tratta delle stesse informazioni che verrebbero restituite se fosse necessario chiamare l'operazione per ottenere un prodotto specifico .
products\<product name>\product.description.html: Descrizione del prodotto, corrispondente alla proprietà description dell'entità prodotto nell'API REST.

modelli

La cartella templates contiene la configurazione per i modelli di posta elettronica dell'istanza del servizio.

<template name>\configuration.json: Configurazione per il modello di posta elettronica.
<template name>\body.html: Corpo del modello di posta elettronica.

Passaggi successivi

Per informazioni su altri metodi di gestione dell'istanza del servizio, vedere: