Configuratie van API Management-service opslaan en configureren met behulp van Git

Elke API Management service-exemplaar onderhoudt een configuratiedatabase met informatie over de configuratie en metagegevens voor het service-exemplaar. U kunt wijzigingen aanbrengen in het service-exemplaar door een instelling te wijzigen in de Azure Portal, met behulp van Azure-hulpprogramma's zoals Azure PowerShell of de Azure CLI, of door een REST API-aanroep te maken. Naast deze methoden kunt u de configuratie van uw service-exemplaar beheren met behulp van Git, waardoor scenario's zoals:

  • Configuratieversiebeheer : verschillende versies van uw serviceconfiguratie downloaden en opslaan
  • Bulkconfiguratiewijzigingen : breng wijzigingen aan in meerdere onderdelen van uw serviceconfiguratie in uw lokale opslagplaats en integreer de wijzigingen terug naar de server met één bewerking
  • Vertrouwde Git-hulpprogrammaketen en -werkstroom : gebruik de Git-hulpprogramma's en werkstromen waarmee u al bekend bent

In het volgende diagram ziet u een overzicht van de verschillende manieren waarop u uw API Management service-exemplaar kunt configureren.

Diagram dat manieren vergelijkt om Azure API Management te configureren.

Wanneer u wijzigingen aanbrengt in uw service met behulp van de Azure Portal, Azure-hulpprogramma's zoals Azure PowerShell of de Azure CLI of de REST API, beheert u uw serviceconfiguratiedatabase met behulp van het https://{name}.management.azure-api.net eindpunt, zoals aan de rechterkant van het diagram wordt weergegeven. Aan de linkerkant van het diagram ziet u hoe u uw serviceconfiguratie kunt beheren met behulp van Git- en Git-opslagplaats voor uw service in https://{name}.scm.azure-api.net.

De volgende stappen bieden een overzicht van het beheren van uw API Management service-exemplaar met behulp van Git.

  1. Toegang tot Git-configuratie in uw service
  2. Sla uw serviceconfiguratiedatabase op in uw Git-opslagplaats
  3. De Git-opslagplaats klonen naar uw lokale computer
  4. Haal de meest recente opslagplaats naar uw lokale computer en voer wijzigingen door en push wijzigingen terug naar uw opslagplaats
  5. De wijzigingen van uw opslagplaats implementeren in uw serviceconfiguratiedatabase

In dit artikel wordt beschreven hoe u Git inschakelt en gebruikt om uw serviceconfiguratie te beheren en biedt een verwijzing naar de bestanden en mappen in de Git-opslagplaats.

Belangrijk

Deze functie is ontworpen voor gebruik met kleine tot middelgrote API Management serviceconfiguraties, zoals configuraties met een geëxporteerde grootte van minder dan 10 MB of met minder dan 10.000 entiteiten. Services met een groot aantal entiteiten (producten, API's, bewerkingen, schema's enzovoort) kunnen onverwachte fouten ondervinden bij het verwerken van Git-opdrachten. Als u dergelijke fouten tegenkomt, verkleint u de grootte van uw serviceconfiguratie en probeert u het opnieuw. Neem contact op met De ondersteuning van Azure als u hulp nodig hebt.

Beschikbaarheid

Belangrijk

Deze functie is beschikbaar in de Premium-, Standard-, Basic- en Developer-lagen van API Management.

Toegang tot Git-configuratie in uw service

  1. Navigeer in de Azure Portal naar uw API Management exemplaar.

  2. Selecteer Opslagplaats in het linkermenu onder Implementatie en infrastructuur.

Schermopname van het openen van de Git-configuratie voor API Management.

Sla de serviceconfiguratie op in de Git-opslagplaats

Waarschuwing

Geheimen die niet zijn gedefinieerd als benoemde waarden, worden opgeslagen in de opslagplaats en blijven in de geschiedenis. Benoemde waarden bieden een veilige plaats voor het beheren van constante tekenreekswaarden, inclusief geheimen, voor alle API-configuratie en -beleidsregels, zodat u ze niet rechtstreeks hoeft op te slaan in uw beleidsinstructies. Zie Benoemde waarden gebruiken in Azure API Management-beleid voor meer informatie.

Voordat u de opslagplaats kloont, slaat u de huidige status van de serviceconfiguratie op in de opslagplaats.

  1. Selecteer Opslaan in opslagplaats op de pagina Opslagplaats.

  2. Breng gewenste wijzigingen aan in het bevestigingsscherm, zoals de naam van de vertakking voor het opslaan van de configuratie en selecteer Opslaan.

Na enkele ogenblikpen wordt de configuratie opgeslagen en wordt de configuratiestatus van de opslagplaats weergegeven, inclusief de datum en tijd van de laatste configuratiewijziging en de laatste synchronisatie tussen de serviceconfiguratie en de opslagplaats.

Zodra de configuratie is opgeslagen in de opslagplaats, kan deze worden gekloond.

Zie Tenantconfiguratie - Opslaan voor informatie over het opslaan van de serviceconfiguratie met behulp van de REST API.

Toegangsreferenties ophalen

Als u een opslagplaats wilt klonen, hebt u naast de URL naar uw opslagplaats een gebruikersnaam en wachtwoord nodig.

  1. Selecteer op de pagina Opslagplaatstoegangsreferenties boven aan de pagina.

  2. Noteer de gebruikersnaam die is opgegeven op de pagina Toegangsreferenties .

  3. Als u een wachtwoord wilt genereren, moet u eerst controleren of de vervaldatum is ingesteld op de gewenste vervaldatum en -tijd en selecteert u Genereren.

Belangrijk

Noteer dit wachtwoord. Zodra u deze pagina verlaat, wordt het wachtwoord niet meer weergegeven.

De opslagplaats op uw lokale machine klonen

In de volgende voorbeelden wordt het Git Bash-hulpprogramma van Git voor Windows gebruikt, maar u kunt elk Git-hulpprogramma gebruiken waarmee u bekend bent.

Open uw Git-hulpprogramma in de gewenste map en voer de volgende opdracht uit om de Git-opslagplaats naar uw lokale computer te klonen met behulp van de volgende opdracht:

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

Geef de gebruikersnaam en het wachtwoord op wanneer u hierom wordt gevraagd.

Als er fouten optreden, wijzigt u de git clone opdracht om de gebruikersnaam en het wachtwoord op te nemen, zoals wordt weergegeven in het volgende voorbeeld.

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

Als dit een fout oplevert, probeert u de URL te coderen van het wachtwoordgedeelte van de opdracht. U kunt dit snel doen door Visual Studio te openen en de volgende opdracht uit te voeren in het venster Direct. Als u het venster Direct wilt openen, opent u een oplossing of project in Visual Studio (of maakt u een nieuwe lege consoletoepassing) en kiest u Windows, Direct in het menu Foutopsporing.

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

Gebruik het gecodeerde wachtwoord samen met uw gebruikersnaam en opslagplaatslocatie om de Git-opdracht te maken.

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

Nadat het klonen is voltooid, wijzigt u de map in uw opslagplaats door een opdracht uit te voeren zoals hieronder.

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

Als u de configuratie hebt opgeslagen in een andere vertakking dan de standaardbranch (master), raadpleegt u de vertakking:

git checkout <branch_name>

Zodra de opslagplaats is gekloond, kunt u deze bekijken en ermee werken in uw lokale bestandssysteem. Zie de verwijzing naar bestands- en mapstructuur van de lokale Git-opslagplaats voor meer informatie.

Uw lokale opslagplaats bijwerken met de meest recente configuratie van het service-exemplaar

Als u wijzigingen aanbrengt in uw API Management service-exemplaar in de Azure Portal of met andere Azure-hulpprogramma's, moet u deze wijzigingen opslaan in de opslagplaats voordat u de lokale opslagplaats kunt bijwerken met de meest recente wijzigingen.

Als u wijzigingen wilt opslaan met behulp van de Azure Portal, selecteert u Opslaan in opslagplaats op het tabblad Opslagplaats voor uw API Management-exemplaar.

Als u vervolgens uw lokale opslagplaats wilt bijwerken:

  1. Zorg ervoor dat u zich in de map voor uw lokale opslagplaats bevindt. Als u de git clone opdracht zojuist hebt voltooid, moet u de map wijzigen in uw opslagplaats door een opdracht als volgt uit te voeren.

    cd {name}.scm.azure-api.net/
    
  2. Geef de volgende opdracht uit in de map voor uw lokale opslagplaats.

    git pull
    

Wijzigingen van uw lokale opslagplaats naar de serveropslagplaats pushen

Als u wijzigingen vanuit uw lokale opslagplaats naar de serveropslagplaats wilt pushen, moet u uw wijzigingen doorvoeren en deze vervolgens naar de serveropslagplaats pushen. Als u uw wijzigingen wilt doorvoeren, opent u het Git-opdrachtprogramma, schakelt u over naar de map van uw lokale opslagplaats en geeft u de volgende opdrachten uit.

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

Voer de volgende opdracht uit om alle doorvoeringen naar de server te pushen.

git push

Serviceconfiguratiewijzigingen implementeren in het API Management service-exemplaar

Zodra uw lokale wijzigingen zijn doorgevoerd en naar de serveropslagplaats zijn gepusht, kunt u deze implementeren in uw API Management service-exemplaar.

  1. Navigeer in de Azure Portal naar uw API Management exemplaar.

  2. Selecteer In> het linkermenu onder Implementatie en infrastructuur opslagplaatsimplementeren in API Management.

  3. Voer op de pagina Opslagplaatsconfiguratie implementeren de naam in van de vertakking met de gewenste configuratiewijzigingen en selecteer eventueel Abonnementen van verwijderde producten verwijderen. Selecteer Opslaan.

Zie Tenantconfiguratie - Implementeren voor meer informatie over het uitvoeren van deze bewerking met behulp van de REST API.

Naslaginformatie over bestands- en mapstructuur van lokale Git-opslagplaats

De bestanden en mappen in de lokale Git-opslagplaats bevatten de configuratiegegevens over het service-exemplaar.

Item Beschrijving
hoofdmap api-management Bevat configuratie op het hoogste niveau voor het service-exemplaar
apiReleases-map Bevat de configuratie voor de API-releases in het service-exemplaar
APIS-map Bevat de configuratie voor de API's in het service-exemplaar
apiVersionSets-map Bevat de configuratie voor de API-versiesets in het service-exemplaar
map back-ends Bevat de configuratie voor de back-endbronnen in het service-exemplaar
groepsmap Bevat de configuratie voor de groepen in het service-exemplaar
map met beleidsregels Bevat het beleid in het service-exemplaar
portalStyles-map Bevat de configuratie voor de aanpassingen van de ontwikkelaarsportal in het service-exemplaar
portalTemplates-map Bevat de configuratie voor de sjablonen voor de ontwikkelaarsportal in het service-exemplaar
productmap Bevat de configuratie voor de producten in het service-exemplaar
map sjablonen Bevat de configuratie voor de e-mailsjablonen in het service-exemplaar

Elke map kan een of meer bestanden bevatten, en in sommige gevallen een of meer mappen, bijvoorbeeld een map voor elke API, product of groep. De bestanden in elke map zijn specifiek voor het entiteitstype dat wordt beschreven door de mapnaam.

Bestandstype Doel
json Configuratie-informatie over de respectieve entiteit
html Beschrijvingen van de entiteit, vaak weergegeven in de ontwikkelaarsportal
xml Beleidsinstructies
css Opmaakmodellen voor het aanpassen van de ontwikkelaarsportal

Deze bestanden kunnen worden gemaakt, verwijderd, bewerkt en beheerd in uw lokale bestandssysteem en de wijzigingen die zijn geïmplementeerd in uw API Management service-exemplaar.

Notitie

De volgende entiteiten bevinden zich niet in de Git-opslagplaats en kunnen niet worden geconfigureerd met Behulp van Git.

  • Gebruikers
  • Abonnementen
  • Benoemde waarden
  • Entiteiten voor ontwikkelaarsportals anders dan stijlen en sjablonen

Hoofdmap api-management

De hoofdmap api-management bevat een configuration.json bestand met informatie op het hoogste niveau over het service-exemplaar in de volgende indeling.

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

De eerste vier instellingen (RegistrationEnabled, UserRegistrationTerms, UserRegistrationTermsEnableden UserRegistrationTermsConsentRequired) worden toegewezen aan de volgende instellingen op het tabblad Identiteiten in de sectie Ontwikkelaarsportal .

Identiteitsinstelling Kaarten naar
RegistrationEnabled Aanwezigheid van id-provider voor gebruikersnaam en wachtwoord
UserRegistrationTerms Gebruiksvoorwaarden voor het tekstvak voor aanmelding van gebruikers
UserRegistrationTermsEnabled Selectievakje Gebruiksvoorwaarden weergeven op de aanmeldingspagina
UserRegistrationTermsConsentRequired Selectievakje Toestemming vereisen
RequireUserSigninEnabled Het selectievakje anonieme gebruikers omleiden naar aanmeldingspagina

De volgende vier instellingen (DelegationEnabled, DelegationUrl, DelegatedSubscriptionEnableden DelegationValidationKey) worden toegewezen aan de volgende instellingen op het tabblad Delegatie in de sectie Ontwikkelaarsportal .

Delegeringsinstelling Kaarten naar
DelegationEnabled Selectievakje Voor aanmelden delegeren &
DelegationUrl Tekstvak Eindpunt-URL voor delegering
DelegatedSubscriptionEnabled Selectievakje Productabonnement delegeren
DelegationValidationKey Tekstvak Validatiesleutel delegeren

De laatste instelling, $ref-policywordt toegewezen aan het algemene beleidsinstructiesbestand voor het service-exemplaar.

apiReleases-map

De apiReleases map bevat een map voor elke API-release die is geïmplementeerd in een productie-API en bevat de volgende items.

  • apiReleases\<api release Id>\configuration.json - Configuratie voor de release, met informatie over de releasedatums. Dit is dezelfde informatie die wordt geretourneerd als u een specifieke releasebewerking wilt aanroepen.

APIS-map

De apis map bevat een map voor elke API in het service-exemplaar, die de volgende items bevat.

  • apis\<api name>\configuration.json - Configuratie voor de API, met informatie over de URL van de back-endservice en de bewerkingen. Dit is dezelfde informatie die wordt geretourneerd als u de Get a specific API-bewerking aanroept.
  • apis\<api name>\api.description.html - Beschrijving van de API, die overeenkomt met de description eigenschap van de API-entiteit in de REST API.
  • apis\<api name>\operations\ - Map met <operation name>.description.html bestanden die zijn toegewezen aan de bewerkingen in de API. Elk bestand bevat de beschrijving van één bewerking in de API, die wordt toegewezen aan de description eigenschap van de bewerkingsentiteit in de REST API.

apiVersionSets-map

De apiVerionSets map bevat een map voor elke API-versieset die is gemaakt voor een API en bevat de volgende items.

  • apiVersionSets\<api version set Id>\configuration.json - Configuratie voor de versieset. Dit is dezelfde informatie die wordt geretourneerd als u de bewerking Een specifieke versieset ophalen zou aanroepen.

groepsmap

De groups map bevat een map voor elke groep die is gedefinieerd in het service-exemplaar.

  • groups\<group name>\configuration.json - Configuratie voor de groep. Dit is dezelfde informatie die wordt geretourneerd als u de bewerking Een specifieke groep ophalen zou aanroepen.
  • groups\<group name>\description.html - Beschrijving van de groep, die overeenkomt met de description eigenschap van de groepsentiteit.

map met beleidsregels

De policies map bevat de beleidsinstructies voor uw service-exemplaar.

  • policies\global.xml - Beleid dat is gedefinieerd op globaal bereik voor uw service-exemplaar.
  • policies\apis\<api name>\ - Als u beleidsregels hebt gedefinieerd in het API-bereik, bevinden ze zich in deze map.
  • policies\apis\<api name>\<operation name>\ map: als u beleidsregels hebt gedefinieerd in het bewerkingsbereik, bevinden ze zich in deze map in <operation name>.xml bestanden die zijn toegewezen aan de beleidsinstructies voor elke bewerking.
  • policies\products\ - Als u beleidsregels hebt gedefinieerd op productbereik, bevinden ze zich in deze map, die bestanden bevat <product name>.xml die zijn toegewezen aan de beleidsinstructies voor elk product.

portalStyles-map

De portalStyles map bevat configuratie- en opmaakmodellen voor het aanpassen van de afgeschafte ontwikkelaarsportal van het service-exemplaar.

  • portalStyles\configuration.json - Bevat de namen van de opmaakmodellen die door de ontwikkelaarsportal worden gebruikt
  • portalStyles\<style name>.css - Elk <style name>.css bestand bevat stijlen voor de ontwikkelaarsportal (Preview.css en Production.css standaard).

portalTemplates-map

De portalTemplates map bevat sjablonen voor het aanpassen van de afgeschafte ontwikkelaarsportal van het service-exemplaar.

  • portalTemplates\<template name>\configuration.json - Configuratie van de sjabloon.
  • portalTemplates\<template name>\<page name>.html - Oorspronkelijke en gewijzigde HTML-pagina's van de sjabloon.

productmap

De products map bevat een map voor elk product dat is gedefinieerd in het service-exemplaar.

  • products\<product name>\configuration.json - Configuratie voor het product. Dit is dezelfde informatie die zou worden geretourneerd als u de actie Een specifiek product ophalen zou aanroepen.
  • products\<product name>\product.description.html - Beschrijving van het product, dat overeenkomt met de description eigenschap van de productentiteit in de REST API.

sjablonen

De templates map bevat configuratie voor de e-mailsjablonen van het service-exemplaar .

  • <template name>\configuration.json - Configuratie voor de e-mailsjabloon.
  • <template name>\body.html - Hoofdtekst van de e-mailsjabloon.

Volgende stappen

Zie voor meer informatie over andere manieren om uw service-exemplaar te beheren: