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

Artikel
10/24/2023

VAN TOEPASSING OP: Ontwikkelaar | Basic | Standaard | Premium

In elk exemplaar van de API Management-service wordt een configuratiedatabase met informatie over de configuratie en metagegevens voor het service-exemplaar bijgehouden. U kunt wijzigingen aanbrengen in het service-exemplaar door een instelling in Azure Portal te wijzigen, Azure-hulpprogramma's zoals Azure PowerShell of de Azure-CLI te gebruiken of een REST API-aanroep te maken. Daarnaast kunt u de configuratie van uw service-exemplaar beheren met behulp van Git, om scenario's zoals de volgende mogelijk te maken:

Configuratieversiebeheer : verschillende versies van uw serviceconfiguratie downloaden en opslaan
Wijzigingen in bulkconfiguratie : 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 om uw API Management-service-exemplaar te configureren.

Diagram dat manieren vergelijkt om Azure API Management te configureren.

Wanneer u wijzigingen aanbrengt in uw service met behulp van 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.

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

In dit artikel wordt beschreven hoe u Git inschakelt en gebruikt voor het beheren van uw serviceconfiguratie en 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. Voor services met een groot aantal entiteiten (producten, API's, bewerkingen, schema's, enzovoort) kunnen onverwachte fouten optreden bij het verwerken van Git-opdrachten. Als u dergelijke fouten tegenkomt, beperkt u de grootte van uw serviceconfiguratie en probeert u het opnieuw. Neem contact op met De ondersteuning van Azure als u hulp nodig hebt.

Toegang tot Git-configuratie in uw service

Navigeer naar uw API Management-exemplaar in Azure Portal.
Selecteer Opslagplaats in het linkermenu onder Implementatie en infrastructuur.

Schermopname van toegang tot Git-configuratie voor API Management.

De serviceconfiguratie opslaan in de Git-opslagplaats

Let op

Geheimen die niet zijn gedefinieerd als benoemde waarden, worden opgeslagen in de opslagplaats en blijven behouden 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 deze niet rechtstreeks in uw beleidsinstructies hoeft op te slaan. 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.

Selecteer Opslaan in opslagplaats op de pagina Opslagplaats.
Breng de gewenste wijzigingen aan in het bevestigingsscherm, zoals de naam van de vertakking voor het opslaan van de configuratie en selecteer Opslaan.

Na enkele ogenblikken 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, naast de URL naar uw opslagplaats, hebt u een gebruikersnaam en een wachtwoord nodig.

Selecteer op de pagina Opslagplaats toegangsreferenties boven aan de pagina.
Noteer de gebruikersnaam die is opgegeven op de pagina Toegangsreferenties .
Als u een wachtwoord wilt genereren, controleert u eerst of de vervaldatum en -tijd zijn ingesteld op de gewenste vervaldatum en selecteert u Vervolgens 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 van het wachtwoordgedeelte van de opdracht te coderen. 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 zoals hieronder uit te voeren.

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

Als u de configuratie hebt opgeslagen in een andere vertakking dan de standaardbranch (master), bekijkt 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 naslaginformatie over 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 Azure Portal of met andere Azure-hulpprogramma's, moet u deze wijzigingen opslaan in de opslagplaats voordat u uw lokale opslagplaats kunt bijwerken met de meest recente wijzigingen.

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

Als u vervolgens uw lokale opslagplaats wilt bijwerken:

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 zoals hieronder uit te voeren.
```
cd {name}.scm.azure-api.net/
```
Voer in de map voor uw lokale opslagplaats de volgende opdracht uit.
```
git pull
```

Wijzigingen van uw lokale opslagplaats naar de serveropslagplaats pushen

Als u wijzigingen van 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 voert 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

Wijzigingen in de serviceconfiguratie 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.

Navigeer naar uw API Management-exemplaar in Azure Portal.
Selecteer in het linkermenu onder Implementatie en infrastructuur opslagplaats>implementeren in API Management.
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.

Verwijzing naar 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-beheer	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
back-endmap	Bevat de configuratie voor de back-endbronnen in het service-exemplaar
map groepen	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 met 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 betreffende entiteit
html	Beschrijvingen van de entiteit, die vaak worden weergegeven in de ontwikkelaarsportal
xml	Beleidsinstructies
Css	Opmaakmodellen voor het aanpassen van de ontwikkelaarsportal

Deze bestanden kunnen worden gemaakt, verwijderd, bewerkt en beheerd op 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
Beleidsfragmenten

Hoofdmap api-beheer

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 aan
RegistrationEnabled	Aanwezigheid van id-provider voor gebruikersnaam en wachtwoord
UserRegistrationTerms	Gebruiksvoorwaarden voor het tekstvak voor gebruikersregistratie
UserRegistrationTermsEnabled	Selectievakje Gebruiksvoorwaarden weergeven op aanmeldingspagina
UserRegistrationTermsConsentRequired	Selectievakje Toestemming vereisen
RequireUserSigninEnabled	Het selectievakje Anonieme gebruikers omleiden naar de aanmeldingspagina

De volgende vier instellingen (, , en ) worden toegewezen aan de volgende instellingen op het tabblad Delegatie in de sectie Ontwikkelaarsportal.DelegationValidationKeyDelegatedSubscriptionEnabledDelegationUrlDelegationEnabled

Instelling voor delegering	Kaarten aan
DelegationEnabled	Selectievakje aanmelden en registreren delegeren
DelegationUrl	Tekstvak Eindpunt-URL voor delegering
DelegatedSubscriptionEnabled	Selectievakje Productabonnement delegeren
DelegationValidationKey	Tekstvak Validatiesleutel delegeren

De laatste instelling, $ref-policywordt toegewezen aan het bestand met globale beleidsinstructies 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 zou worden geretourneerd als u de get a specifieke release-bewerking zou 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 zou worden geretourneerd als u de get a specifieke API-bewerking zou aanroepen.
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 is toegewezen aan de description eigenschap van de bewerkingsentiteit in de REST API.

apiVersionSets-map

De apiVersionSets 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 Get a specific version set aanroept.

map groepen

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 zou worden geretourneerd als u de get a specifieke groepsbewerking 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 - Beleidsregels die zijn gedefinieerd op globaal bereik voor uw service-exemplaar.
policies\apis\<api name>\ - Als u beleidsregels hebt gedefinieerd in het API-bereik, bevinden deze 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 deze 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 get a specifieke productbewerking 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: