Erste Schritte mit API Center
In dieser Übung führen Sie die folgenden Schritte aus:
Erstellen Sie einen API Center-Dienst.
Definieren von Metadateneigenschaften.
Hinzufügen von APIs zu Ihrem API Center.
Hinzufügen von Bereitstellungen und Umgebungen.
Voraussetzungen
Um mit der Verwaltung Ihrer APIs über das API Center zu beginnen, benötigen Sie Folgendes:
- Ein Azure-Abonnement.
- Der in Ihrem Abonnement registrierte Microsoft.ApiCenter-Ressourcenanbieter.
- Mindestens eine Rollenzuweisung für Mitwirkende oder gleichwertige Berechtigungen im Azure-Abonnement.
Hinweis
Wenn dies noch nicht geschehen ist, müssen Sie den Ressourcenanbieter Microsoft.ApiCenter in Ihrem Abonnement registrieren.
- Melden Sie sich beim Azure-Portal an.
- Geben Sie in der Suchleiste Abonnements ein.
- Wählen Sie das Abonnement aus, unter dem Sie das API Center erstellen möchten.
- Wählen Sie im linken Menü unter „Ressourcen“ die Option Ressourcenanbieter aus.
- Suchen Sie in der Liste der Ressourcenanbieter nach Microsoft.ApiCenter. Wenn er nicht registriert ist, wählen Sie Registrieren aus.
Schritt 1: Erstellen eines API Center-Diensts
Geben Sie in die Suchleiste API-Centers ein.
Wählen Sie + Erstellen aus.
Wählen Sie auf der Registerkarte Grundlagen die folgenden Einstellungen aus, oder geben Sie sie ein:
a. Wählen Sie Ihr Azure-Abonnement.
b. Wählen Sie eine vorhandene Ressourcengruppe aus, oder klicken Sie auf Neu erstellen, um eine zu erstellen.
c. Geben Sie einen Namen für Ihr API-Center ein. Er muss in der Region eindeutig sein, in der Sie Ihr API Center erstellen.
d. Wählen Sie in Region eine der verfügbaren Regionen für API Center aus.
e. Wählen Sie für den Preisplan kostenlose Testversion (0 USD für 90 Tage) aus.
f. Klicken Sie auf Überprüfen + erstellen.
h. Wenn die Überprüfung abgeschlossen ist, wählen Sie Erstellen aus.
Nach der Bereitstellung ist Ihr API-Center einsatzbereit!
Um CLI-Referenzbefehle lokal auszuführen, installieren Sie die Azure CLI, und melden Sie sich mit dem folgenden Befehl an.
az login
Hinweis
Wenn dies noch nicht geschehen ist, müssen Sie den Ressourcenanbieter Microsoft.ApiCenter in Ihrem Abonnement registrieren.
Führen Sie den folgenden Befehl aus, um den Ressourcenanbieter zu registrieren
az provider register –namespace Microsoft.ApiCenter
Schritt 1: Erstellen eines API Center-Diensts
Erstellen Sie eine Ressourcengruppe indem Sie den folgenden Befehl ausführen und folgendes übergeben:
- Name der Ressourcengruppe --name – Beispiel. Contoso
- Standort --location – Beispiel. Eastus
az group create –-name contoso –-location eastus
Hinweis
az apic-Befehle erfordern die APIC-Erweiterung Azure CLI-Erweiterung. Wenn Sie az apic-Befehle nicht verwendet haben, wird die Erweiterung dynamisch installiert, wenn Sie den ersten az apic-Befehl ausführen. Sie können die Erweiterung auch manuell installieren. Hier finden Si weitere Informationen zu Azure CLI-Erweiterungen.
Erstellen Sie ein API Center, indem Sie den folgenden Befehl ausführen und folgendes übergeben:
- API Center-Dienstname -n – Beispiel. contoso-apis
- Ressourcengruppe -g – Beispiel. Contoso
- Standort --l – Beispiel. Eastus
az apic create -n contoso-apis -g contoso -l eastus
Hinweis
Standardmäßig wird das API Center im Rahmen der kostenlosen Preisstufe erstellt.
Hinweis
Das Erstellen eines API Center-Diensts wird derzeit von VS Code nicht unterstützt. Erstellen Sie eine mithilfe der Azure CLI oder des Azure-Portals.
Schritt 2: Definieren von Metadateneigenschaften
API Center verwendet Metadateneigenschaften, um die APIs in Ihrem Bestand zu organisieren und Vorgänge wie Filtern, Suchen usw. zu ermöglichen.
Hinweis
Fügen Sie keine sensiblen, vertraulichen oder persönlichen Informationen in die Titel oder Namen der Metadateneigenschaften ein.
Wie viele andere Organisationen möchte Contoso, dass alle seine APIs einen Freigabeprozess durchlaufen, bevor sie für die Nutzung zur Verfügung stehen, und sicherstellen, dass für alle APIs eine Compliance-Prüfung durchgeführt wird. Die Organisation verfügt auch über APIs, die öffentlich zugänglich sind, und solche, die ausschließlich für den internen Gebrauch entwickelt wurden. Um dies in allen APIs durchzusetzen, fügen wir drei benutzerdefinierte Metadateneigenschaften hinzu:
- API-genehmigende Person vom Typ „String“
- Complianceüberprüfung des Typs „Vordefinierte Auswahlmöglichkeiten“
- Öffentlich zugänglich vom Typ „Boolean“
Wählen Sie im linken Menü Ressourcen > Metadaten > + Neue Metadaten.
Geben Sie auf der Registerkarte Details Informationen zur Eigenschaft ein.
a. Geben Sie bei Title API-genehmigende Person ein.
b. Geben Sie in Beschreibung Standard-API-genehmigende Person ein.
c. Wählen Sie String aus, und wählen Sie Weiter aus.
Wählen Sie auf der Registerkarte Zuweisungen für APIs die Option erforderlich aus. Wählen Sie Optional für Bereitstellungen und Umgebungen aus. Wählen Sie Weiter aus.
Klicken Sie auf Erstellen
Wiederholen Sie dieselben Schritte für die Eigenschaft Öffentlich zugänglich wie in der Abbildung unten dargestellt. Wählen Sie als Datentyp Boolean.
Wählen Sie auf der Registerkarte Zuweisungen für APIs die Option erforderlich aus. Wählen Sie Nicht anwendbar für Bereitstellungen und Umgebungen aus. Wählen Sie Weiter aus.
Klicken Sie auf Erstellen
Wiederholen Sie dieselben Schritte für die Eigenschaft Complianceüberprüfung wie in der Abbildung unten dargestellt. Wählen Sie für den Typ Vordefinierte Auswahlmöglichkeiten aus, und fügen Sie drei Optionen hinzu, Nicht gestartet, Wird ausgeführt und Abgeschlossen.
Wählen Sie auf der Registerkarte Zuweisungen für APIs die Option erforderlich aus. Wählen Sie für „Bereitstellungen und Umgebungen“ Nicht zutreffend aus.
Wählen Sie Weiter aus.
Ein JSON-Metadatenschema für Ihre APIs steht jetzt für Sie zum Anzeigen, Bearbeiten und Herunterladen zur Verfügung. Zum Anzeigen wählen Sie Metadatenschema anzeigen aus, und dann wählen Sie APIs aus der Dropdownliste aus.
Dadurch wird ein modales Element auf der rechten Seite mit Metadatendetails geöffnet, die integrierte Eigenschaften aus dem API Center enthalten, z. B. LifecycleStage, Name, Description, TermsOfService. Wenn Sie zum Ende der Datei scrollen, sehen Sie die benutzerdefinierten Metadaten, die Sie in den vorherigen Schritten hinzugefügt haben, wie unten dargestellt.
Hinweis
Sie können Eigenschaften im Schema jederzeit hinzufügen und bearbeiten und sie sofort auf alle APIs in Ihrem API Center anwenden.
Erstellen Sie ein neues Metadatenschema, indem Sie den folgenden Befehl ausführen, um Folgendes festzulegen:
- Metadatenname für api-approver
- Schema mit Eigenschaftstyp als Zeichenfolge und Titel als API-Approver
- Zuweisungen soweit erforderlich für APIs, jedoch optional für Umgebung und Bereitstellung
az apic metadata create -g contoso -n contoso-apis --metadata-name "api-approver" --schema '{"type":"string","title":"API Approver"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
Wiederholen Sie die gleichen Schritte für:
- Metadatenname für public-facing
- Schema mit Eigenschaftstyp als boolesch und Titel als Public Facing
- Zuweisungen soweit erforderlich für APIs, jedoch optional für Umgebung und Bereitstellung
Durch Ausführen des folgenden Befehls:
az apic metadata create -g contoso -n contoso-apis --metadata-name "public-facing" --schema '{"type":"boolean", "title":"Public Facing"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
Wiederholen Sie zuletzt die gleichen Schritte für:
- Metadatenname für compliance-review
- Schema mit Eigenschaftstyp als Zeichenfolge und Titel als Compliance Review
- Zuweisungen soweit erforderlich für APIs, jedoch optional für Umgebung und Bereitstellung
Durch Ausführen des folgenden Befehls:
az apic metadata create -g contoso -n contoso-apis --metadata-name "compliance-review" --schema '{"type":"string","title":"Compliance Review", "oneOf":[{"const":"Not Started","description":""},{"const":"In Progress","description":""},{"const":"Completed","description":""}]}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
Sie können den folgenden Befehl ausführen, um eine Liste aller definierten Metadaten im API Center anzuzeigen.
az apic metadata list -g <resource-group-name> -n <api-center-name>
Hinweis
Sie können Eigenschaften im Schema jederzeit hinzufügen und bearbeiten und sie sofort auf alle APIs in Ihrem API Center anwenden.
Hinweis
Diese Aktion wird aktuell nicht auf VS Code unterstützt. Erstellen Sie eine mithilfe der Azure CLI oder des Azure-Portals.
Schritt 3: Hinzufügen von APIs zum Bestand
Die Organisation Contoso möchte im Rahmen ihrer internen Qualifizierungsbemühungen technische Konferenzen für ihre Ingenieurteams empfehlen. Wir werden eine Konferenz-API mit Referenten, Sitzungen und Themen hinzufügen.
Konferenz-API-URL: https://bigconference.azurewebsites.net/
Für die folgenden Schritte können Sie die OpenAPI-Definition von der obigen Website kopieren und als JSON-Datei auf Ihrem lokalen Computer speichern. Oder ersetzen Sie beim Hinzufügen einer API zum Bestand eine andere API-Definition.
Navigieren Sie im Portal zu Ihrem API-Center.
Wählen Sie im linken Menü Ressourcen > APIs > + API registrieren.
Fügen Sie auf der Seite API registrieren die folgenden erforderlichen Informationen für die API hinzu. Sie sehen die benutzerdefinierten Metadateneigenschaften API-genehmigende Person, *Öffentlich zugänglich und Complianceüberprüfung, die Sie in den vorherigen Schritten unten auf der Seite definiert haben.
Um Ihre erstellte API anzuzeigen, wählen Sie im linken Menü Ressourcen > APIs > Konferenz-API aus.
Auf der Registerkarte Übersicht finden Sie eine Ansicht der API-Konfiguration. Erweitern Sie Details, um zusätzliche Informationen wie API-Version und -Bereitstellungen anzuzeigen und zu bearbeiten (zu diesem Zeitpunkt sind keine Bereitstellungen vorhanden).
Sie möchten normalerweise eine API-Definition für Ihre API-Version hinzufügen, und API Center unterstützt Formate für Textspezifikationen, einschließlich OpenAPI 2 und OpenAPI 3 für REST.
Um eine Definition hinzuzufügen,
- Wählen Sie im linken Menü Ressourcen > APIs > Wählen Sie Ihre API (Konferenz-API) aus.
- Erweitern Sie Details, und wählen Sie Versionen aus.
- Wählen Sie Ihre Version (v1) aus, und erweitern Sie Details.
- Wählen Sie unter „Details“ Definitionen > Definition hinzufügen aus.
Sie können die Azure API Center-Erweiterung für Visual Studio Code verwenden, um eine API in Ihrer API-Instanz zu registrieren.
Schritt 1: Installieren Sie die Erweiterung.
Schritt 2: Öffnen Sie die Befehlspalette, „STRG+UMSCHALT+P“, und geben Sie API Center: Registrieren der API ein.
Folgen Sie den Anweisungen, um die folgenden Informationen für Ihre API bereitzustellen.
| Registrieren der API | Schritt für Schritt |
|---|---|
| Auswählen des API Center-Diensts | Auswählen Ihrer API Center-Instanz |
| API-Titel | Geben Sie den Namen Ihrer API ein (Konferenz-API) |
| API-Typ | REST |
| API-Versionstitel | Geben Sie einen Versionsnamen für Ihre API ein (v1) |
| API-Versionslebenszyklus | Wählen Sie einen Lebenszyklus aus der Dropdownliste (Entwicklung) |
| API-Definitionstitel | Geben Sie einen Namen für Ihre Definition ein (Konferenz-API-Definition) |
| Name der API-Spezifikation | Wählen Sie eine Spezifikation aus der Dropdownliste (OpenAPI 2) |
| API-Definitionsdatei zum Importieren auswählen | Durchsuchen und Auswählen der Definitionsdatei aus Ihrem Speicher |
Aktualisieren Sie die Registerkarte „API Center-Erweiterung“, und Ihre neu erstellte API wird in der jeweiligen APIC-Instanz/Ressource angezeigt.
Verwenden Sie den folgenden Befehl, um eine neue API zu erstellen, indem Sie folgendes übergeben:
- Ressourcengruppe -g – Beispiel. Contoso
- API Center-Dienstname -n – Beispiel. contoso-api-center
- Titel --title – Beispiel. Konferenz-API
- API-ID --api-id – Beispiel. conference-api
- Typ --type – Beispiel. REST
az apic api create -g contoso -n contoso-apis --title "Conference API" --api-id conference-api --type REST
Erstellen Sie eine API-Version, indem Sie den folgenden Befehl ausführen und folgendes übergeben:
- Ressourcengruppe -g – Beispiel. contoso
- API Center-Dienstname -n – Beispiel. contoso-apis
- API-ID --api-id – Beispiel. conference-api
- Titel --title – Beispiel. V1.2.2
- Version-ID --version-id – Beispiel. 2024-07-03
- Lebenszyklusphase --lifecycle-stage – Beispiel. Design
az apic api version create -g contoso -n contoso-apis --api-id conference-api --title v1.2.2 --version-id 2024-07-03 --lifecycle-stage design
Sie können auch eine API-Definition für Ihre API-Version hinzufügen, und API Center unterstützt Formate für Textspezifikationen, einschließlich OpenAPI 2 und OpenAPI 3 für REST.
Verwenden Sie zum Hinzufügen einer Definition den folgenden Befehl, und übergeben Sie Folgendes:
- Ressourcengruppe -g – Beispiel. contoso
- API Center-Dienstname -n – Beispiel. contoso-apis
- API-ID --api-id – Beispiel. conference-api
- Version-ID --version-id – Beispiel. 2024-07-03
- Titel --title – Beispiel. OpenAPI
- Definitions-ID --definition-id – Beispiel. openapi
az apic api definition create -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --title OpenAPI --definition-id openapi
Zum Importieren einer OpenAPI-Definitionsdatei aus einer URL verwenden Sie den Befehl az apic api definition import-specification. Beispiel: https://zcusa.951200.xyz/cli/azure/apic/api/definition?view=azure-cli-latest#az-apic-api-definition-import-specification-examples
az apic api definition import-specification -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --definition-id openapi --format "link" --value 'https://petstore3.swagger.io/api/v3/openapi.json' --specification '{"name":"openapi","version":"3.0.2"}'
Schritt 4: Hinzufügen von Bereitstellungen und Umgebungen
Umgebungen
Eine Umgebung (Entwicklung, Tests, Staging oder Produktion) stellt einen Speicherort dar, an dem eine API-Laufzeit bereitgestellt wird. Die API-Plattformexperten von Contoso definieren in ihrer API Center-Instanz zwei Umgebungen – Test und Produktion –, um die verschiedenen API-Laufzeiten in ihrer Organisation zu verwalten und nachzuverfolgen.
Um eine Umgebung zu erstellen:
Wählen Sie im linken Menü Ressourcen > Umgebungen > + Neue Umgebung aus.
Fügen Sie die folgenden Informationen hinzu.
Klicken Sie auf Erstellen.
Wiederholen Sie die gleichen Schritte für die Produktionsumgebung.
Führen Sie zum Erstellen einer Umgebung den folgenden CLI-Befehl aus
az apic environment create -g contoso -n contoso-apis --title ContosoTesting --environment-id contosotesting --type testing
Wiederholen Sie das Gleiche für die Produktionsumgebung
az apic environment create -g contoso -n contoso-apis-new --title ContosoProduction --environment-id contosoproduction --type production
Hinweis
Das Erstellen von Umgebungen wird derzeit für VS Code nicht unterstützt. Verwenden Sie die Azure CLI oder die Azure-Portaloption für diesen Schritt.
Bereitstellungen
Für jede API-Laufzeit in einer bestimmten Umgebung wird ein eindeutiger Speicherort (Adresse) bereitgestellt, an dem Benutzerinnen und Benutzer mit Ihrer API interagieren können. Dieser Speicherort wird als Bereitstellung bezeichnet, und eine einzelne API-Version könnte zwei Bereitstellungen aufweisen – eine Staging- und eine Produktionsbereitstellung.
Contoso verfügt über eine API, die Konferenz-API, die wir den von uns erstellten Umgebungen zuordnen.
Navigieren Sie im Portal zu Ihrem API-Center.
Wählen Sie im linken Menü APIs und dann eine API aus, z. B. die Konferenz-API.
Erweitern Sie auf der Seite Konferenz-API Details > Bereitstellungen > + Bereitstellung hinzufügen.
Fügen Sie die folgenden Informationen hinzu:
a. Wählen Sie Contoso Testing aus der Dropdownliste für das Feld Umgebung aus.
b. Wählen Sie für die Definition Auswählen aus, wählen Sie die API-Version v1 aus der Dropdownliste, und dann die zuvor hinzugefügte Definition aus. Klicken Sie auf Auswählen.
c. Nachdem Sie die Definition erfolgreich hinzugefügt haben, fügen Sie eine Basis-Laufzeit-URL hinzu, die für die API in der ausgewählten Umgebung spezifisch ist.
Führen Sie den folgenden CLI-Befehl aus, um eine Bereitstellung zu erstellen und der Umgebung zuzuordnen, die wir im obigen Schritt erstellt haben.
az apic api deployment create -g contoso-corporation -s contoso-api-center --deployment-id "v1-conference-api" --title "Conference OpenAPI 2" --description "Conference Demo API deployment." --api-id conference-api --environment-id "/workspaces/default/environments/contoso-testing" --definition-id "/workspaces/default/apis/conference-api/versions/v1/definitions/conference-openapi-2" --server '{"runtimeUri":["https://conferenceapi.azurewebsites.net/"]}'
Hinweis
Das Erstellen von Bereitstellungen wird derzeit für VS Code nicht unterstützt. Verwenden Sie die Azure CLI oder die Azure-Portaloption für diesen Schritt.