Come salvare e configurare la configurazione del servizio Gestione API tramite GitHow to save and configure your API Management service configuration using Git

Ogni istanza del servizio Gestione API gestisce un database di configurazione che contiene informazioni sulla configurazione e i metadati dell'istanza del servizio.Each API Management service instance maintains a configuration database that contains information about the configuration and metadata for the service instance. Per apportare modifiche all'istanza del servizio è possibile modificare un'impostazione nel portale di pubblicazione, usare un cmdlet di PowerShell o eseguire una chiamata all'API REST.Changes can be made to the service instance by changing a setting in the publisher portal, using a PowerShell cmdlet, or making a REST API call. Oltre a questi metodi, è possibile gestire la configurazione dell'istanza del servizio tramite Git. Ciò consente scenari di gestione del servizio diversi, ad esempio:In addition to these methods, you can also manage your service instance configuration using Git, enabling service management scenarios such as:

  • Controllo delle versioni della configurazione: downolad e archiviazione di versioni diverse della configurazione del servizioConfiguration versioning - download and store different versions of your service configuration
  • Modifiche in blocco alla configurazione: esecuzione di modifiche in più punti della configurazione del servizio all'interno del repository locale e integrazione delle modifiche nel server con un'unica operazioneBulk configuration changes - make changes to multiple parts of your service configuration in your local repository and integrate the changes back to the server with a single operation
  • 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àFamiliar Git toolchain and workflow - use the Git tooling and workflows that you are already familiar with

Il diagramma seguente offre una panoramica dei diversi modi in cui è possibile configurare un'istanza del servizio Gestione API.The following diagram shows an overview of the different ways to configure your API Management service instance.

Configurare Git

Quando si apportano modifiche al servizio tramite il portale di pubblicazione, i cmdlet di PowerShell o l'API REST, la gestione del database di configurazione del servizio avviene tramite l'endpoint https://{name}.management.azure-api.net , come mostrato nella parte destra del diagramma.When you make changes to your service using the publisher portal, PowerShell cmdlets, or the REST API, you are managing your service configuration database using the https://{name}.management.azure-api.net endpoint, as shown on the right side of the diagram. 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.The left side of the diagram illustrates how you can manage your service configuration using Git and Git repository for your service located at https://{name}.scm.azure-api.net.

I passaggi seguenti offrono una panoramica della gestione dell'istanza del servizio Gestione API tramite Git.The following steps provide an overview of managing your API Management service instance using Git.

  1. Accedere alla configurazione Git nel servizioAccess Git configuration in your service
  2. Salvare il database di configurazione del servizio nel repository GitSave your service configuration database to your Git repository
  3. Clonare il repository Git nel computer localeClone the Git repo to your local machine
  4. Estrarre il repository più recente nel computer locale ed eseguire il commit e il push delle modifiche nel repositoryPull the latest repo down to your local machine, and commit and push changes back to your repo
  5. Distribuire le modifiche dal repository nel database di configurazione del servizioDeploy the changes from your repo into your service configuration database

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.This article describes how to enable and use Git to manage your service configuration and provides a reference for the files and folders in the Git repository.

Accedere alla configurazione Git nel servizioAccess Git configuration in your service

È possibile visualizzare rapidamente lo stato della configurazione di Git visualizzando l'icona Git nell'angolo superiore destro del portale di pubblicazione.You can quickly view the status of your Git configuration by viewing the Git icon in the upper-right corner of the publisher portal. In questo esempio, il messaggio di stato indica che ci sono modifiche non salvate nel repository.In this example, the status message indicates that there are unsaved changes to the repository. Questo avviene perché il database di configurazione del servizio Gestione API non è ancora stato salvato nel repository.This is because the API Management service configuration database has not yet been saved to the repository.

Stato Git

Per visualizzare e configurare le impostazioni di configurazione di Git, è possibile fare clic sull'icona Git oppure fare clic sul menu Security (Sicurezza) e passare alla scheda Configuration repository (Repository configurazioni).To view and configure your Git configuration settings, you can either click the Git icon, or click the Security menu and navigate to the Configuration repository tab.

Abilitare GIT

Importante

Eventuali segreti non definiti come proprietà verranno archiviati nel repository e rimarranno nella cronologia di questo finché non si disabilita e riabilita l'accesso a Git.Any secrets that are not defined as properties will be stored in the repository and will remain in its history until you disable and re-enable Git access. Le proprietà 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.Properties provide a secure place to manage constant string values, including secrets, across all API configuration and policies, so you don't have to store them directly in your policy statements. Per altre informazioni, vedere Come usare le proprietà nei criteri di Gestione API di Azure.For more information, see How to use properties in Azure API Management policies.

Per informazioni sull'abilitazione o la disabilitazione dell'accesso a Git mediante l'API REST, vedere la pagina relativa a questo argomento.For information on enabling or disabling Git access using the REST API, see Enable or disable Git access using the REST API.

Per salvare la configurazione del servizio nel repository GitTo save the service configuration to the Git repository

Il primo passaggio prima della clonazione del repository corrisponde al salvataggio dello stato corrente della configurazione del servizio nel repository.The first step before cloning the repository is to save the current state of the service configuration to the repository. Fare clic su Save configuration to repository.Click Save configuration to repository.

Salvare la configurazione

Apportare le modifiche desiderate nella schermata di conferma e fare clic su Ok per salvare.Make any desired changes on the confirmation screen and click Ok to save.

Salvare la configurazione

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.After a few moments the configuration is saved, and the configuration status of the repository is displayed, including the date and time of the last configuration change and the last synchronization between the service configuration and the repository.

Stato della configurazione

Dopo che la configurazione è stata salvata nel repository, può essere clonata.Once the configuration is saved to the repository, it can be cloned.

Per informazioni sull'esecuzione di questa operazione tramite l'API REST, vedere la pagina relativa all'esecuzione del commit di uno snapshot della configurazione tramite l'API REST.For information on performing this operation using the REST API, see Commit configuration snapshot using the REST API.

Per clonare il repository nel computer localeTo clone the repository to your local machine

Per clonare un repository, sono necessari l'URL del repository, un nome utente e una password.To clone a repository, you need the URL to your repository, a user name, and a password. Il nome utente e l'URL sono visualizzati nella parte superiore della scheda Configuration repository .The user name and URL are displayed near the top of the Configuration repository tab.

Clonare in Git

La password viene generata nella parte inferiore della scheda Configuration repository .The password is generated at the bottom of the Configuration repository tab.

Generare password

Per generare una password, verificare prima di tutto che il campo Expiry (Scadenza) sia impostato sulla data e sull'ora di scadenza desiderate e quindi fare clic su Generate Token (Genera token).To generate a password, first ensure that the Expiry is set to the desired expiration date and time, and then click Generate Token.

Password

Importante

Prendere nota della password.Make a note of this password. Una volta chiusa questa pagina, la password non verrà più visualizzata.Once you leave this page the password will not be displayed again.

Gli esempi seguenti usano lo strumento Git Bash di Git per Windows ma è possibile usare qualsiasi strumento Git con cui si abbia familiarità.The following examples use the Git Bash tool from Git for Windows but you can use any Git tool that you are familiar with.

Aprire lo strumento Git nella cartella desiderata ed eseguire il comando seguente per clonare il repository Git nel computer locale, usando il comando fornito dal portale di pubblicazione.Open your Git tool in the desired folder and run the following command to clone the git repository to your local machine, using the command provided by the publisher portal.

git clone https://bugbashdev4.scm.azure-api.net/

Quando richiesto,specificare il nome utente e la password.Provide the user name and password when prompted.

Se si ricevono errori, provare a modificare il comando git clone includendo il nome utente e password, come illustrato nell'esempio seguente.If you receive any errors, try modifying your git clone command to include the user name and password, as shown in the following example.

git clone https://username:password@bugbashdev4.scm.azure-api.net/

Se viene generato un errore, provare a codificare con URL la parte della password del comando.If this provides an error, try URL encoding the password portion of the command. Un metodo rapido per eseguire questa operazione consiste nell'aprire Visual Studio, eseguendo il comando seguente nella finestra di controllo immediato.One quick way to do this is to open Visual Studio, and issue the following command in the Immediate Window. 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.To open the Immediate Window, open any solution or project in Visual Studio (or create a new empty console application), and choose Windows, Immediate from the Debug menu.

?System.NetWebUtility.UrlEncode("password from publisher portal")

Per creare il comando git, usare la password codificata con il nome utente e il percorso del repository.Use the encoded password along with your user name and repository location to construct the git command.

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

Una volta clonato il repository, è possibile visualizzarlo e usarlo nel file system locale.Once the repository is cloned you can view and work with it in your local file system. Per altre informazioni, vedere Informazioni di riferimento sulla struttura di file e cartelle del repository Git locale.For more information, see File and folder structure reference of local Git repository.

Per aggiornare il repository locale con la configurazione dell'istanza del servizio più recenteTo update your local repository with the most current service instance configuration

Se si apportano modifiche all'istanza del servizio Gestione API nel portale di pubblicazione o tramite l'API REST, è necessario salvare le modifiche nel repository prima di aggiornare il repository locale con le modifiche più recenti.If you make changes to your API Management service instance in the publisher portal or using the REST API, you must save these changes to the repository before you can update your local repository with the latest changes. A tale scopo, fare clic su Save configuration to repository (Salva configurazione in repository) nella scheda Configuration repository (Repository configurazioni) del portale di pubblicazione e quindi eseguire questo comando nel repository locale.To do this, click Save configuration to repository on the Configuration repository tab in the publisher portal, and then issue the following command in your local repository.

git pull

Prima di eseguire git pull assicurarsi di trovarsi nella cartella del repository locale.Before running git pull ensure that you are in the folder for your local repository. Se è appena stato eseguito il comando git clone , è necessario modificare la directory con quella del repository tramite un comando simile al seguente.If you have just completed the git clone command, then you must change the directory to your repo by running a command like the following.

cd bugbashdev4.scm.azure-api.net/

Per eseguire il push delle modifiche dal repository locale al repository del serverTo push changes from your local repo to the server repo

Per eseguire il push delle modifiche dal repository locale al repository del server, è prima necessario eseguire il commit delle modifiche stesse.To push changes from your local repository to the server repository, you must commit your changes and then push them to the server repository. Per eseguire il commit delle modifiche, aprire lo strumento dei comandi Git, passare alla directory del repository locale ed eseguire i comandi seguenti.To commit your changes, open your Git command tool, switch to the directory of your local repository, and issue the following commands.

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

Per eseguire il push di tutti i commit nel server, eseguire il comando seguente.To push all of the commits to the server, run the following command.

git push

Per distribuire le modifiche alla configurazione del servizio all'istanza del servizio Gestione APITo deploy any service configuration changes to the API Management service instance

Dopo il commit e il push delle modifiche locali nel repository del server, è possibile distribuire le modifiche all'istanza del servizio Gestione API.Once your local changes are committed and pushed to the server repository, you can deploy them to your API Management service instance.

Distribuisci

Per informazioni sull'esecuzione di questa operazione tramite l'API REST, vedere la pagina relativa alla distribuzione delle modifiche al database di configurazione tramite l'API REST.For information on performing this operation using the REST API, see Deploy Git changes to configuration database using the REST API.

Informazioni di riferimento sulla struttura di file e cartelle del repository Git localeFile and folder structure reference of local Git repository

I file e cartelle nel repository Git locale contengono le informazioni di configurazione dell'istanza del servizio.The files and folders in the local git repository contain the configuration information about the service instance.

ItemItem DescrizioneDescription
Cartella api-management radiceroot api-management folder Contiene la configurazione di livello superiore per l'istanza del servizioContains top-level configuration for the service instance
Cartella apisapis folder Contiene la configurazione per le API nell'istanza del servizioContains the configuration for the apis in the service instance
Cartella groupsgroups folder Contiene la configurazione per i gruppi nell'istanza del servizioContains the configuration for the groups in the service instance
Cartella policiespolicies folder Contiene i criteri dell'istanza del servizioContains the policies in the service instance
Cartella portalStylesportalStyles folder Contiene la configurazione delle personalizzazioni del portale per sviluppatori nell'istanza del servizioContains the configuration for the developer portal customizations in the service instance
Cartella productsproducts folder Contiene la configurazione per i prodotti nell'istanza del servizioContains the configuration for the products in the service instance
Cartella templatestemplates folder Contiene la configurazione per i modelli nell'istanza del servizioContains the configuration for the email templates in the service instance

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.Each folder can contain one or more files, and in some cases one or more folders, for example a folder for each API, product, or group. I file all'interno di ogni cartella sono specifici per il tipo di entità descritto dal nome della cartella.The files within each folder are specific for the entity type described by the folder name.

Tipo fileFile type ScopoPurpose
jsonjson Informazioni di configurazione dell'entità corrispondenteConfiguration information about the respective entity
htmlhtml Descrizioni delle entità, spesso visualizzate nel portale per sviluppatoriDescriptions about the entity, often displayed in the developer portal
xmlxml Policy statementsPolicy statements
csscss Fogli di stile per la personalizzazione del portale per sviluppatoriStyle sheets for developer portal customization

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.These files can be created, deleted, edited, and managed on your local file system, and the changes deployed back to the your API Management service instance.

Nota

Le entità seguenti non sono contenute nel repository Git e non possono essere configurate tramite Git.The following entities are not contained in the Git repository and cannot be configured using Git.

  • UtentiUsers
  • SottoscrizioniSubscriptions
  • ProprietàProperties
  • Entità del portale per sviluppatori diverse dagli stiliDeveloper portal entities other than styles

Cartella api-management radiceRoot api-management folder

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.The root api-management folder contains a configuration.json file that contains top-level information about the service instance in the following format.

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

Le prime quattro impostazioni (RegistrationEnabled, UserRegistrationTerms, UserRegistrationTermsEnabled e UserRegistrationTermsConsentRequired) sono mappate alle impostazioni seguenti della scheda Identities (Identità) della sezione Security (Sicurezza).The first four settings (RegistrationEnabled, UserRegistrationTerms, UserRegistrationTermsEnabled, and UserRegistrationTermsConsentRequired) map to the following settings on the Identities tab in the Security section.

ImpostazioneIdentity setting Mapping aMaps to
RegistrationEnabledRegistrationEnabled Redirect anonymous users to Redirect anonymous users to sign-in page checkbox
UserRegistrationTermsUserRegistrationTerms Terms of use on user signup Terms of use on user signup textbox
UserRegistrationTermsEnabledUserRegistrationTermsEnabled Show terms of use on signup pageShow terms of use on signup page checkbox
UserRegistrationTermsConsentRequiredUserRegistrationTermsConsentRequired Richiedi consenso Require consent checkbox

Impostazioni di identità

Le quattro impostazioni successive (DelegationEnabled, DelegationUrl, DelegatedSubscriptionEnabled e DelegationValidationKey) sono mappate alle impostazioni seguenti della scheda Delegation (Delega) della sezione Security (Sicurezza).The next four settings (DelegationEnabled, DelegationUrl, DelegatedSubscriptionEnabled, and DelegationValidationKey) map to the following settings on the Delegation tab in the Security section.

ImpostazioneDelegation setting Mapping aMaps to
DelegationEnabledDelegationEnabled Casella di controllo Delegate sign-in & sign-up (Delega accesso e iscrizione)Delegate sign-in & sign-up checkbox
DelegationUrlDelegationUrl Delegation endpoint URLDelegation endpoint URL textbox
DelegatedSubscriptionEnabledDelegatedSubscriptionEnabled Delegate product subscriptionDelegate product subscription checkbox
DelegationValidationKeyDelegationValidationKey Delegate Validation KeyDelegate Validation Key textbox

Impostazioni di delega

L'impostazione finale, $ref-policy, esegue il mapping al file di istruzioni dei criteri globali per l'istanza del servizio.The final setting, $ref-policy, maps to the global policy statements file for the service instance.

Cartella apisapis folder

La cartella apis contiene, per ogni API nell'istanza del servizio, una cartella contenente a sua volta gli elementi seguenti.The apis folder contains a folder for each API in the service instance which contains the following items.

  • apis\<api name>\configuration.json: configurazione dell'API. Contiene informazioni relative all'URL del servizio back-end e alle operazioni.apis\<api name>\configuration.json - this is the configuration for the API and contains information about the backend service URL and the operations. Si tratta delle stesse informazioni che verrebbero restituite se fosse necessario ottenere un'API specifica con export=true nel formato application/json.This is the same information that would be returned if you were to call Get a specific API with export=true in application/json format.
  • apis\<api name>\api.description.html: descrizione dell'API. Corrisponde alla proprietà description dell'entità relativa all'API.apis\<api name>\api.description.html - this is the description of the API and corresponds to the description property of the API entity.
  • apis\<api name>\operations\: questa cartella contiene i file <operation name>.description.html mappati alle operazioni nell'API.apis\<api name>\operations\ - this folder contains <operation name>.description.html files that map to the operations in the 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.Each file contains the description of a single operation in the API which maps to the description property of the operation entity in the REST API.

Cartella groupsgroups folder

La cartella groups contiene una cartella per ogni gruppo definito nell'istanza del servizio.The groups folder contains a folder for each group defined in the service instance.

  • groups\<group name>\configuration.json: configurazione del gruppo.groups\<group name>\configuration.json - this is the configuration for the group. Si tratta delle stesse informazioni che verrebbero restituite se fosse necessario chiamare l'operazione per ottenere un gruppo specifico .This is the same information that would be returned if you were to call the Get a specific group operation.
  • groups\<group name>\description.html: descrizione del gruppo. Corrisponde alla proprietà description dell'entità relativa al gruppo.groups\<group name>\description.html - this is the description of the group and corresponds to the description property of the group entity.

Cartella policiespolicies folder

La cartella policies contiene le istruzioni dei criteri per l'istanza del servizio.The policies folder contains the policy statements for your service instance.

  • policies\global.xml : contiene i criteri definiti in ambito globale per l'istanza del servizio.policies\global.xml - contains policies defined at global scope for your service instance.
  • policies\apis\<api name>\: se sono presenti criteri definiti nell'ambito delle API, tali criteri sono contenuti in questa cartella.policies\apis\<api name>\ - if you have any policies defined at API scope, they are contained in this folder.
  • Cartella policies\apis\<api name>\<operation name>\: se sono presenti criteri definiti nell'ambito delle operazioni, tali criteri sono contenuti in questa cartella all'interno dei file <operation name>.xml mappati alle istruzioni dei criteri per ogni operazione.policies\apis\<api name>\<operation name>\ folder - if you have any policies defined at operation scope, they are contained in this folder in <operation name>.xml files that map to the policy statements for each operation.
  • policies\products\: se sono presenti 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.policies\products\ - if you have any policies defined at product scope, they are contained in this folder, which contains <product name>.xml files that map to the policy statements for each product.

Cartella portalStylesportalStyles folder

La cartella portalStyles contiene la configurazione e i fogli di stile delle personalizzazioni del portale per sviluppatori per l'istanza del servizio.The portalStyles folder contains configuration and style sheets for developer portal customizations for the service instance.

  • portalStyles\configuration.json : contiene i nomi dei fogli di stile usati dal portale per sviluppatoriportalStyles\configuration.json - contains the names of the style sheets used by the developer portal
  • portalStyles\<style name>.css: ogni file <style name>.css contiene stili per il portale per sviluppatori (per impostazione predefinita, Preview.css e Production.css).portalStyles\<style name>.css - each <style name>.css file contains styles for the developer portal (Preview.css and Production.css by default).

Cartella productsproducts folder

La cartella products contiene una cartella per ogni prodotto definito nell'istanza del servizio.The products folder contains a folder for each product defined in the service instance.

  • products\<product name>\configuration.json: configurazione del prodotto.products\<product name>\configuration.json - this is the configuration for the product. Si tratta delle stesse informazioni che verrebbero restituite se fosse necessario chiamare l'operazione per ottenere un prodotto specifico .This is the same information that would be returned if you were to call the Get a specific product operation.
  • products\<product name>\product.description.html: descrizione del prodotto. Corrisponde alla proprietà description dell'entità relativa al prodotto nell'API REST.products\<product name>\product.description.html - this is the description of the product and corresponds to the description property of the product entity in the REST API.

Modellitemplates

La cartella templates contiene la configurazione per i modelli di posta elettronica dell'istanza del servizio.The templates folder contains configuration for the email templates of the service instance.

  • <template name>\configuration.json : configurazione del modello di posta elettronica.<template name>\configuration.json - this is the configuration for the email template.
  • <template name>\body.html : corpo del modello di posta elettronica.<template name>\body.html - this is the body of the email template.

Passaggi successiviNext steps

Per informazioni su altri metodi di gestione dell'istanza del servizio, vedere:For information on other ways to manage your service instance, see:

Guardare un video introduttivoWatch a video overview