Speichern und Konfigurieren der API Management-Dienstkonfiguration mit Git

Artikel
05/12/2023

GILT FÜR: Developer | Basic | Standard | Premium

Jede API Management-Dienstinstanz verwaltet eine Konfigurationsdatenbank, die Informationen über die Konfiguration und die Metadaten für die Dienstinstanz enthält. Änderungen an der Dienstinstanz können durch Ändern einer Einstellung im Azure-Portal, mithilfe von Azure-Tools wie Azure PowerShell und Azure CLI oder durch einen REST-API-Aufruf vorgenommen werden. Neben diesen Methoden können Sie die Dienstinstanzkonfiguration mithilfe Git verwalten, um Szenarien wie die folgenden zu ermöglichen:

Verwaltung von Konfigurationsversionen: Laden Sie verschiedene Versionen der Dienstkonfiguration herunter, und speichern Sie sie.
Massenänderungen an der Konfiguration: Ändern Sie in einem einzelnen Vorgang mehrere Teile der Dienstkonfiguration in Ihrem lokalen Repository, und integrieren Sie die Änderungen wieder auf dem Server.
Vertraute Git-Tools und -Workflows: Verwenden Sie die Git-Tools und -Workflows, die Sie bereits kennen.

Das folgende Diagramm zeigt eine Übersicht über die verschiedenen Methoden zum Konfigurieren Ihrer API Management-Dienstinstanz.

Abbildung: Vergleich von zwei Möglichkeiten zum Konfigurieren von Azure API Management

Wenn Sie den Dienst mit dem Azure-Portal, Azure-Tools wie Azure PowerShell oder Azure CLI oder mit der REST-API ändern, verwalten Sie die Konfigurationsdatenbank des Diensts mithilfe des Endpunkts https://{name}.management.azure-api.net, der auf der rechten Seite des Diagramms angezeigt wird. Die linke Seite des Diagramms veranschaulicht, wie Sie die Dienstkonfiguration mithilfe von Git und dem Git-Repository für Ihren Dienst unter https://{name}.scm.azure-api.netverwalten können.

Die folgenden Schritte bieten eine Übersicht über die Verwaltung Ihrer API Management-Dienstinstanz mit Git.

Zugreifen auf die Git-Konfiguration in Ihrem Dienst
Speichern der Konfigurationsdatenbank des Diensts in Ihrem Git-Repository
Klonen des Git-Repositorys auf Ihrem lokalen Computer
Herunterladen des aktuellen Repositorys auf Ihren lokalen Computer und Ausführen eines Commits und Übertragen der Änderungen zurück in das Repository
Bereitstellen der Änderungen aus dem Repository in der Konfigurationsdatenbank des Diensts

In diesem Artikel wird das Aktivieren und Verwenden von Git für die Verwaltung der Dienstkonfiguration beschrieben. Zudem enthält er eine Referenz für die Dateien und Ordner im Git-Repository.

Wichtig

Dieses Feature ist für die Arbeit mit kleinen bis mittleren API Management-Dienstkonfigurationen bestimmt, etwa Konfigurationen mit einer exportierten Größe von weniger als 10 MB oder mit weniger als 10.000 Entitäten. Bei Diensten mit einer großen Anzahl von Entitäten (Produkte, APIs, Vorgänge, Schemas usw.) können beim Verarbeiten von Git-Befehlen unerwartete Fehler auftreten. Wenn solche Fehler auftreten, verringern Sie die Größe Ihrer Dienstkonfiguration, und versuchen Sie es erneut. Wenden Sie sich an den Azure-Support, wenn Sie Hilfe benötigen.

Zugreifen auf die Git-Konfiguration in Ihrem Dienst

Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.
Wählen Sie im Menü auf der linken Seite unter Bereitstellung und Infrastruktur die Option Repository aus.

Screenshot: Zugreifen auf Git-Konfiguration für API Management

Speichern der Dienstkonfiguration im Git-Repository

Achtung

Geheimnisse, die nicht als benannte Werte definiert sind, werden im Repository gespeichert und verbleiben in dessen Verlauf. Benannte Werte stellen einen sicheren Ort zum Verwalten von konstanten Zeichenfolgenwerten, einschließlich Geheimnissen, für alle API-Konfigurationen und -Richtlinien dar. Sie müssen sie also nicht direkt in Ihren Richtlinienanweisungen speichern. Weitere Informationen finden Sie unter Verwenden benannter Werte in Azure API Management-Richtlinien.

Speichern Sie vor dem Klonen des Repositorys den aktuellen Zustand der Dienstkonfiguration im Repository.

Wählen Sie auf der Seite Repository die Option In Repository speichern aus.
Nehmen Sie alle gewünschten Änderungen auf dem Bestätigungsbildschirm vor, z. B. Ändern des Namens des Branch zum Speichern der Konfiguration, und wählen Sie Speichern aus.

Nach einigen Augenblicken wird die Konfiguration gespeichert, und der Konfigurationsstatus des Repositorys wird angezeigt, einschließlich des Datums und der Uhrzeit der letzten Konfigurationsänderung und der letzten Synchronisierung zwischen der Dienstkonfiguration und dem Repository.

Sobald die Konfiguration im Repository gespeichert wurde, kann sie geklont werden.

Informationen zum Speichern der Dienstkonfiguration mithilfe der REST-API finden Sie unter Mandantenkonfiguration: Speichern.

Abrufen von Zugriffsanmeldeinformationen

Um ein Repository zu klonen, benötigen Sie zusätzlich zur URL Ihres Repositorys einen Benutzernamen und ein Kennwort.

Wählen Sie auf der Seite Repository am oberen Rand die Option Anmeldeinformationen für Zugriff aus.
Notieren Sie den Benutzernamen auf der Seite Anmeldeinformationen für Zugriff.
Um ein Kennwort zu generieren, stellen Sie zuerst sicher, dass der Ablauf auf das gewünschte Ablaufdatum und die gewünschte Uhrzeit festgelegt ist, und wählen Sie dann Generieren aus.

Wichtig

Notieren Sie sich dieses Kennwort. Das Kennwort wird nicht wieder angezeigt, nachdem Sie diese Seite verlassen haben.

Klonen des Repositorys auf Ihrem lokalen Computer

In den folgenden Beispielen wird das Tool Git Bash aus Git für Windows verwendet, Sie können aber auch ein beliebiges Git-Tool verwenden, mit dem Sie vertraut sind.

Öffnen Sie Ihr Git-Tool im gewünschten Ordner, und führen Sie den folgenden Befehl zum Klonen des Git-Repositorys auf Ihrem lokalen Computer aus. Verwenden Sie dazu den folgenden Befehl:

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

Geben Sie bei entsprechender Aufforderung den Benutzernamen und das Kennwort ein.

Wenn Sie Fehlermeldungen erhalten, ändern Sie den Befehl git clone , sodass er den Benutzernamen und das Kennwort enthält, wie im folgenden Beispiel gezeigt.

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

Wenn dies zu einem Fehler führt, codieren Sie den Kennwortteil des Befehls als URL. Eine schnelle Möglichkeit, dies zu erreichen, ist, Visual Studio zu öffnen und den folgenden Befehl im Direktfensterauszugeben. Um das Direktfenster zu öffnen, öffnen Sie eine Projektmappe oder ein Projekt in Visual Studio (oder erstellen Sie eine neue leere Konsolenanwendung), und wählen Sie im Menü Debuggen erst Fenster und dann Direkt aus.

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

Verwenden Sie das verschlüsselte Kennwort zusammen mit Ihrem Benutzernamen und dem Repositoryspeicherort, um den Git-Befehl zu erstellen.

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

Nachdem das Klonen abgeschlossen ist, ändern Sie das Verzeichnis in Ihr Repository, indem Sie einen Befehl wie den folgenden ausführen:

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

Wenn Sie die Konfiguration in einem anderen Branch als dem Standardbranch (master) gespeichert haben, checken Sie den Branch aus:

git checkout <branch_name>

Nachdem das Repository geklont wurde, können Sie es anzeigen und in Ihrem lokalen Dateisystem verwenden. Weitere Informationen finden Sie unter Referenz der Datei- und Ordnerstruktur des lokalen Git-Repositorys.

Aktualisieren Ihres lokalen Repositorys mit der aktuellen Dienstinstanzkonfiguration

Wenn Sie Ihre API Management-Dienstinstanz im Azure-Portal oder mithilfe anderer Azure-Tools ändern, müssen Sie diese Änderungen im Repository speichern, bevor Sie Ihr lokales Repository mit den neuesten Änderungen aktualisieren können.

Wählen Sie zum Speichern von Änderungen mithilfe des Azure-Portal auf der Registerkarte Repository für Ihre API Management-Instanz die Option In Repository speichern aus.

Gehen Sie anschließend zum Aktualisieren des lokalen Repositorys wie folgt vor:

Stellen Sie sicher, dass Sie sich im Ordner für das lokale Repository befinden. Wenn Sie den Befehl git clone gerade abgeschlossen haben, müssen Sie das Verzeichnis in Ihr Repository ändern, indem Sie einen Befehl wie den folgenden ausführen:
```
cd {name}.scm.azure-api.net/
```
Geben Sie im Ordner für Ihr lokales Repository den folgenden Befehl aus:
```
git pull
```

Pushen von Änderungen aus Ihrem lokalen Repository in das Serverrepository

Um Änderungen aus Ihrem lokalen Repository in das Serverrepository zu übertragen, müssen Sie einen Commit für die Änderungen ausführen und sie dann in das Serverrepository übertragen. Um einen Commit für die Änderungen auszuführen, öffnen Sie Ihr Git-Befehlstool, wechseln Sie in das Verzeichnis des lokalen Repositorys, und geben Sie die folgenden Befehle aus.

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

Führen Sie den folgenden Befehl aus, um alle Commits auf den Server zu übertragen.

git push

Bereitstellen von Änderungen an der Dienstkonfiguration in der API Management-Dienstinstanz

Sobald ein Commit für Ihre lokalen Änderungen ausgeführt wurde und sie in das Serverrepository übertragen wurden, können Sie sie Ihrer API Management-Dienstinstanz bereitstellen.

Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.
Wählen Sie im Menü auf der linken Seite unter Bereitstellung und Infrastruktur die Option Repository>In API Management bereitstellen.
Geben Sie auf der Seite Repositorykonfiguration bereitstellen den Namen des Branch ein, der die gewünschten Konfigurationsänderungen enthält, und wählen Sie optional Abonnements gelöschter Produkte entfernen aus. Wählen Sie Speichern aus.

Informationen zum Ausführen dieses Vorgangs mithilfe der REST-API finden Sie unter Mandantenkonfiguration: Bereitstellen.

Referenz der Datei- und Ordnerstruktur des lokalen Git-Repositorys

Die Dateien und Ordner im lokalen Git-Repository enthalten die Konfigurationsinformationen der Dienstinstanz.

Element	BESCHREIBUNG
Stammordner „api-management“	Enthält die Konfiguration der obersten Ebene für die Dienstinstanz
Ordner „apiReleases“	Enthält die Konfiguration für die API-Releases in der Dienstinstanz
Ordner „apis“	Enthält die Konfiguration für die APIs in der Dienstinstanz
Ordner „apiVersionSets“	Enthält die Konfiguration für die API-Versionsgruppen in der Dienstinstanz
Ordner „backends“	Enthält die Konfiguration für die Back-End-Ressourcen in der Dienstinstanz
Ordner „groups“	Enthält die Konfiguration für die Gruppen in der Dienstinstanz
Ordner „policies“	Enthält die Richtlinien in der Dienstinstanz
Ordner „portalStyles“	Enthält die Konfiguration für Anpassungen des Entwicklerportals in der Dienstinstanz
Ordner „portalTemplates“	Enthält die Konfiguration für die Entwicklerportalvorlagen in der Dienstinstanz
Ordner „products“	Enthält die Konfiguration für die Produkte in der Dienstinstanz
Ordner „templates“	Enthält die Konfiguration für die E-Mail-Vorlagen in der Dienstinstanz

Jeder Ordner kann eine oder mehrere Dateien enthalten, und in einigen Fällen einen oder mehrere Ordner, z. B. ein Ordner für jede API, jedes Produkt oder jede Gruppe. Die Dateien in jedem Ordner gelten für den Entitätstyp, der durch den Namen des Ordners beschrieben wird.

Dateityp	Zweck
json	Konfigurationsinformationen zur jeweiligen Entität
html	Beschreibungen der Entität, werden häufig im Entwicklerportal angezeigt
Xml	Richtlinienanweisungen
css	Stylesheets für die Anpassung des Entwicklerportals

Diese Dateien können im lokalen System erstellt, gelöscht, bearbeitet und verwaltet werden, und die Änderungen werden wieder in Ihrer API Management-Dienstinstanz bereitgestellt.

Hinweis

Die folgenden Entitäten sind im Git-Repository nicht enthalten und können nicht mithilfe von Git konfiguriert werden.

Benutzer
Abonnements
Benannte Werte
Andere Entitäten des Entwicklerportals als Stile und Vorlagen
Richtlinienfragmente

Stammordner „api-management“

Der Stammordner api-management enthält eine Datei configuration.json, die Informationen der obersten Ebene über die Dienstinstanz im folgenden Format aufweist.

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

Die ersten vier Einstellungen (RegistrationEnabled, UserRegistrationTerms, UserRegistrationTermsEnabled und UserRegistrationTermsConsentRequired) entsprechen den folgenden Einstellungen auf der Registerkarte Identitäten im Abschnitt Entwicklerportal.

Identitätseinstellung	Entsprechung
RegistrationEnabled	Vorhandensein von Benutzername und Kennwort für Identitätsanbieter
UserRegistrationTerms	Nutzungsbedingungen für die Benutzerregistrierung
UserRegistrationTermsEnabled	Nutzungsbedingungen auf der Registrierungsseite anzeigen
UserRegistrationTermsConsentRequired	Zustimmung anfordern
RequireUserSigninEnabled	Anonyme Benutzer zur Anmeldeseite umleiten

Die nächsten vier Einstellungen (DelegationEnabled, DelegationUrl, DelegatedSubscriptionEnabled und DelegationValidationKey) entsprechen den folgenden Einstellungen auf der Registerkarte Delegierung im Abschnitt Entwicklerportal.

Delegierungseinstellung	Entsprechung
DelegationEnabled	Kontrollkästchen Anmeldung und Registrierung delegieren
DelegationUrl	Delegierungsendpunkt-URL
DelegatedSubscriptionEnabled	Produktabonnierung delegieren
DelegationValidationKey	Überprüfungsschlüssel delegieren

Die letzte Einstellung, $ref-policy, entspricht der globalen Datei mit Richtlinienanweisungen für die Dienstinstanz.

Ordner „apiReleases“

Der Ordner apiReleases enthält einen Ordner für jedes API-Release, das in einer Produktions-API bereitgestellt wird, und enthält die folgenden Elemente:

apiReleases\<api release Id>\configuration.json: Konfiguration für das Release mit Informationen zu den Releaseterminen. Dies sind die gleichen Informationen, die zurückgegeben werden, wenn Sie den Vorgang Abrufen eines bestimmten Release aufrufen.

Ordner „apis“

Der Ordner apis enthält einen Ordner für jede API in der Dienstinstanz, der die folgenden Elemente enthält.

apis\<api name>\configuration.json: Konfiguration für die API mit Informationen zur Back-End-Dienst-URL und zu den Vorgängen. Dies sind die gleichen Informationen, die zurückgegeben werden, wenn Sie den Vorgang Abrufen einer bestimmten API aufrufen.
apis\<api name>\api.description.html: Beschreibung der API. Entspricht der Eigenschaft description der API-Entität in der REST-API.
apis\<api name>\operations\: Ordner mit <operation name>.description.html-Dateien, die den Vorgängen in der API entsprechen. Jede Datei enthält die Beschreibung eines einzelnen Vorgangs in der API, die der description-Eigenschaft der Entität „Operation“ in der REST-API entspricht.

Ordner „apiVersionSets“

Der Ordner apiVersionSets enthält einen Ordner für jede für eine API erstellte API-Versionsgruppe sowie die folgenden Elemente:

apiVersionSets\<api version set Id>\configuration.json: Konfiguration für die Versionsgruppe. Dies sind die gleichen Informationen, die zurückgegeben werden, wenn Sie den Vorgang Abrufen einer bestimmten Versionsgruppe aufrufen.

Ordner „groups“

Der Ordner groups enthält einen Ordner für jede in der Dienstinstanz definierte Gruppe.

groups\<group name>\configuration.json: Konfiguration für die Gruppe. Dies sind die gleichen Informationen, die zurückgegeben werden, wenn Sie den Vorgang Abrufen einer bestimmten Gruppe aufrufen.
groups\<group name>\description.html: Beschreibung der Gruppe. Entspricht der Eigenschaft description der Gruppenentität.

Ordner „policies“

Der Ordner policies enthält die Richtlinienanweisungen für Ihre Dienstinstanz.

policies\global.xml: Richtlinien, die im globalen Bereich für Ihre Dienstinstanz definiert sind
policies\apis\<api name>\: Wenn Sie über Richtlinien verfügen, die im API-Bereich definiert sind, sind sie in diesem Ordner enthalten.
Ordner policies\apis\<api name>\<operation name>\: Wenn Sie über Richtlinien verfügen, die im Vorgangsbereich definiert sind, sind sie in diesem Ordner in <operation name>.xml-Dateien enthalten, die den Richtlinienanweisungen für jeden Vorgang entsprechen.
policies\products\: Wenn Sie über Richtlinien verfügen, die im Produktbereich definiert sind, sind sie in diesem Ordner enthalten, der <product name>.xml-Dateien enthält, die den Richtlinienanweisungen für jedes Produkt entsprechen.

Ordner „portalStyles“

Der Ordner portalStyles enthält Konfigurationen und Stylesheets zum Anpassen des veralteten Entwicklerportals für die Dienstinstanz.

portalStyles\configuration.json: Enthält die Namen der Stylesheets, die vom Entwicklerportal verwendet werden.
portalStyles\<style name>.css: Jede <style name>.css-Datei enthält Stile für das Entwicklerportal (standardmäßig Preview.css und Production.css).

Ordner „portalTemplates“

Der Ordner portalTemplates enthält Vorlagen zum Anpassen des veralteten Entwicklerportals der Dienstinstanz.

portalTemplates\<template name>\configuration.json: Konfiguration der Vorlage
portalTemplates\<template name>\<page name>.html: Ursprüngliche und geänderte HTML-Seiten der Vorlage

Ordner „products“

Der Ordner products enthält einen Ordner für jedes in der Dienstinstanz definierte Produkt.

products\<product name>\configuration.json: Konfiguration für das Produkt. Dies sind die gleichen Informationen, die zurückgegeben werden, wenn Sie den Vorgang Abrufen eines bestimmten Produkts aufrufen.
products\<product name>\product.description.html: Beschreibung des Produkts. Entspricht der Eigenschaft description der Entität „Product“ in der REST-API.

Vorlagen

Der Ordner templates enthält die Konfiguration für die E-Mail-Vorlagen der Dienstinstanz.

<template name>\configuration.json: Konfiguration für die E-Mail-Vorlage
<template name>\body.html: Text der E-Mail-Vorlage

Nächste Schritte

Informationen zu anderen Möglichkeiten für die Verwaltung Ihrer Dienstinstanz finden Sie unter:

Teilen über