APIs entwerfen und bearbeiten

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Folgen Sie den Anleitungen auf dieser Seite, um mit Cloud Code APIs zu entwerfen und zu bearbeiten.

Zusätzliche Rollen für das Entwerfen von APIs

Sie benötigen die unten aufgeführten Rollen, um einige der auf dieser Seite beschriebenen Schritte zum Entwerfen und Testen von APIs auszuführen.

Aufgabe	Erforderliche Rollen
APIs mit Gemini Code Assist entwerfen	Gemini for Google Cloud User Service Usage Consumer Weitere Informationen finden Sie unter IAM-Rollen in einem Google Cloud-Projekt für Gemini Code Assist gewähren.
Unternehmenskontext aus Ihren vorhandenen APIs im API-Hub beim Entwerfen von APIs verwenden	Cloud API Hub-Betrachter
Neue APIs im API-Hub registrieren	Cloud API Hub-Bearbeiter oder ‑Administrator
API-Hub-APIs in Cloud Code bearbeiten	Cloud API Hub-Bearbeiter oder ‑Administrator
Simulierter Remote-Server zum Testen von APIs einrichten und verwalten	Artifact Registry-Administrator Cloud Build-Dienstkonto Cloud Run-Administrator Service Usage-Administrator Referenz zu grundlegenden und vordefinierten IAM-Rollen.

APIs mit Gemini Code Assist entwerfen

Vorschau — Gemini Code Assist

Diese Funktion unterliegt den „Nutzungsbedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Nutzungsbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie besehen“ verfügbar und werden möglicherweise nur eingeschränkt unterstützt. Weitere Informationen finden Sie in den Beschreibungen der Startphase.

Mit Cloud Code können Sie der OpenAPI-Spezifikation (OAS) Version 3.0 entsprechende APIs mit Gemini Code Assist entwerfen. Gemini Code Assist kann Unternehmenskontext für die Unterstützung durch generative KI im API-Entwicklungsprozess enthalten. Beim Unternehmenskontext werden die API-Hub-APIs des Projekts als Kontext verwendet, wenn neue APIs generiert werden. Dieser Kontext ist nur für Projekte verfügbar, die den API-Hub verwenden.

Informationen zu den Einrichtungsschritten für die Verwendung der Funktionen in diesem Abschnitt finden Sie unter Gemini Code Assist verwenden.

Hinweis: Derzeit unterstützt Gemini Code Assist das Entwerfen von APIs, die neue mit vorhandenen Objekten kombinieren (sofern der Enterprise-Kontext aktiviert ist). Es werden keine Szenarien unterstützt, bei denen nur Objekte wiederverwendet werden, ohne das neue erstellt werden.

API generieren

So generieren Sie eine API:

1. Klicken Sie im linken Navigationsbereich auf den Zauberstab, um mit Gemini Code Assist eine neue API-Spezifikation zu erstellen. Verwenden Sie diese Methode, um API-Spezifikationen zu erstellen, und nicht den Gemini Code Assist-Chat, da dieser nicht alle Funktionen beim Erstellen von API-Spezifikationen unterstützt.
   
2. Geben Sie im Eingabefenster API-Spezifikation erstellen einen Prompt ein, der die neue API beschreibt.
   1. Wählen Sie bei Bedarf eine Promptvorlage aus den angezeigten Vorlagen-Chips aus. Eine Promptvorlage bietet ein Gerüst für Ihren Prompt, das Ihnen den Einstieg erleichtert.
   2. Geben Sie einen Prompt ein. Weitere Informationen finden Sie unter Effektive Prompts für API-Spezifikationen schreiben.
      
      
3. Gemini Code Assist generiert eine OAS, die die API definiert.
4. Überprüfen Sie die Spezifikation:
   1. Klicken Sie auf Code anzeigen, um die Spezifikation im Code-Editor zu prüfen.
   2. Im API-Renderer-Bereich wird eine Vorschau der API angezeigt, wie sie von Entwicklern gesehen werden kann, einschließlich der API-Beschreibung und weiterer Dokumentation.
   3. Wenn Sie bereits APIs auf dem API-Hub haben, wird dieser Unternehmenskontext verwendet, um Objekte aus anderen APIs im für diese OAS nochmal zu verwenden. Er wird auch im OUTPUT-Bereich aufgelistet:
      
   4. Vielen Dank für Ihr Feedback. Geben Sie Feedback zur generierten Spezifikation, indem Sie im Swagger-Bereich auf eines der Symbole „Mag ich“ oder „Mag ich nicht“ klicken.
      
   5. Wenn Sie Vorschau-Prompts bearbeiten und die Spezifikation neu generieren möchten, klicken Sie auf die Pfeile für den Prompt-Verlauf über den Prompts, um zwischen den vorherigen Prompts zu wechseln.
      
5. Testen Sie die Spezifikation. Sobald die neue Spezifikation vollständig ist, können Sie sie mit einem simulierten Server testen. Weitere Informationen finden Sie unter API mit einem simulierten Server testen.
6. Klicken Sie auf Speichern, um die neue API mit einem Namen Ihrer Wahl zu speichern.
7. Wenn Sie einen Apigee API-Proxy aus dieser Spezifikation erstellen möchten, klicken Sie im Menü Mehr auf API-Proxy erstellen. Dabei wird ein Proxy-Bundle erstellt. Der neue Proxy sollte in der linken Menüliste Ihrer Proxys angezeigt werden. Weitere Informationen zum Erstellen von Proxys über Cloud Code finden Sie in der in Cloud Code integrierten Schritt-für-Schritt-Anleitung zum Erstellen von API-Proxys.
   

Effektive Prompts für API-Spezifikationen schreiben

Die Accuracy und Eignung einer generierten API-Spezifikation hängt weitgehend von dem Prompt ab, der dem Modell bereitgestellt wurde.

Beispiele für gute Prompts:

• Erstellen Sie eine API, mit der Kunden mit verschiedenen Zahlungsmethoden (Kreditkarten, Debitkarten usw.) Bestellungen bezahlen können.
• Akzeptieren Sie Bestellungen für spezielle Kaffeebohnenkäufe über eine API.
• Wir sind ein Pizzaunternehmen und möchten eine spezielle Onlinelösung für die Pizzaauslieferung erstellen. Erstellen Sie eine API, um die Pizzabestellungen anzunehmen.
• API für Lebensmittellieferunternehmen. Kunden können in eine Kombination aus Pizzen, Burgern und Sandwiches bestellen. Alle diese Lebensmitteltypen haben eigene Optionen. Pizzas haben Topping und Größe. Burger haben Toppings und Patty-Varianten. Sandwiches haben Brottypen, Fleischtyp, Gemüse, Käse und individuelle Wünsche.

Diese Beispiele zeigen weniger effektive Prompts. Vermeiden Sie Prompts wie diese:

• Eine API für meinen Shop erstellen Dieser Prompt enthält nicht genügend Informationen, damit das Modell eine vollständige und korrekte Spezifikation generieren könnte.
• Erstellen Sie eine neue Erstattungs-API, in der das Bestellobjekt wiederverwendet wird. Sie müssen nicht angeben, welche Objekte Gemini Code Assist beim Erstellen neuer APIs wiederverwenden soll. Gemini Code Assist erkennt automatisch die für eine Wiederverwendung am besten geeigneten Objekte.

API im API-Hub registrieren

Nachdem Ihre API überprüft wurde und fertig ist, können Sie sie für Entwickler verfügbar machen, indem Sie sie im API-Hub registrieren:

1. Klicken Sie auf Im API-Hub registrieren.
2. Folgen Sie den Aufforderungen zur Registrierung der API. Informationen zur Registrierung im API-Hub und die Art der von Ihnen bereitzustellenden Informationen finden Sie unter APIs registrieren.

API-Hub-APIs aus Cloud Code aktualisieren

Sie können eine neue Version Ihrer API-Hub-Spezifikationen speichern, wenn Sie sie über Cloud Code bearbeiten.

Wenn Sie die Spezifikation als neue Version speichern möchten, klicken Sie im Swagger-Steuerfeld auf die Schaltfläche Weitere Optionen… und dann auf Im API-Hub veröffentlichen. Geben Sie die ID der neuen API-Version an. Die neue Version sollte in der Versionsliste für diese API in der Liste API-Hub in Cloud Code angezeigt werden.

Die Einstellungsdatei verwenden, um das Verhalten von Gemini Code Assist zu steuern

In diesem Abschnitt wird beschrieben, wie Sie in der Einstellungsdatei festlegen, ob und wie Gemini Code Assist verfügbar ist.

Gemini Code Assist deaktivieren oder aktivieren

Nachdem Sie Apigee in Cloud Code eingerichtet haben (siehe Apigee in Cloud Code einrichten), können Sie Ihrer Einstellungsdatei diese Zeile hinzufügen, um alle Gemini Code Assist-Funktionen vorübergehend zu deaktivieren:

"cloudcode.apigee.gemini.enable": false

Entfernen Sie die Zeile oder setzen Sie sie auf true (Standardeinstellung), um Gemini Code Assist wieder zu aktivieren.

Unternehmenskontext in der Spezifikationsgenerierung steuern

Die OAS-Generierung kann Schema, Metadaten und Sicherheitsdefinitionen aus den anderen APIs Ihrer Organisation enthalten. Der Prozess findet ähnliche APIs mithilfe der Objektnamen und Beschreibungen in dem API-Hub-Katalog, auf den Sie zugreifen dürfen. Der Bereitstellungsstatus der API-Hub-APIs wird nicht berücksichtigt.

Der Unternehmenskontext ist standardmäßig aktiviert.

Sie können:

• Die Anzahl der im Unternehmenskontext enthaltenen Änderungen (falls vorhanden) finden Sie im Swagger-Steuerfeld:
• Die enthaltenen Änderungen finden Sie im Bereich Ausgabe:

Fügen Sie diese Zeilen in der Datei settings.json nach "cloudcode.apigee.gemini.enable": true hinzu, um den Unternehmenskontext für die Generierung neuer Spezifikationen zu deaktivieren:

"cloudcode.apigee.gemini.options": {
        "enterpriseContext": {
          "enabled": false,
          "includeMetadata": false,
          "includeSchema": false,
          "includeSecurity": false
        }
    }

Wobei:

• enabled angibt, ob der Unternehmenskontext insgesamt aktiviert ist. Legen Sie false fest, um den Unternehmenskontext zu deaktivieren.
• includeMetadata steuert, ob der Metadatenkontext enthalten ist. Mit dieser Einstellung werden Metadaten von anderen APIs im API-Hub ein- oder ausgeschlossen. includeMetadata gilt nur, wenn enabled auf true eingestellt ist.
• includeSchema steuert, ob der Schemakontext enthalten ist. Mit dieser Einstellung werden Schemainformationen von anderen APIs im API-Hub ein- oder ausgeschlossen. includeSchema gilt nur, wenn enabled auf true eingestellt ist.
• includeSecurity steuert, ob sicherheitsbezogener Kontext enthalten ist. Mit dieser Einstellung werden Sicherheitsinformationen von anderen APIs im API-Hub ein- oder ausgeschlossen. includeSecurity gilt nur, wenn enabled auf true eingestellt ist.

APIs bearbeiten

Wenn Sie vorhandene APIs, die Teil Ihres API-Hub-Katalogs sind, mit Cloud Code bearbeiten möchten, folgen Sie dieser Anleitung. Änderungen, die Sie in Cloud Code vornehmen, können im API-Hub gespeichert werden.

Diese Anleitung richtet sich an Nutzer, die das Gemini Code Assist-Add-on für Apigee nicht verwenden. Informationen zu zusätzlichen Funktionen, die mit Gemini Code Assist beim Entwerfen und Bearbeiten von APIs verfügbar sind, finden Sie unter API mit Gemini Code Assist entwerfen.

Hinweis: Derzeit müssen alle Änderungen an der API, die im API-Hub gespeichert werden, als neue Version gespeichert werden.

So bearbeiten Sie eine API-Spezifikation:

1. Achten Sie darauf, dass das in Cloud Code ausgewählte Projekt das Projekt mit dem API-Hub-Katalog ist, der die zu bearbeitende API enthält.
2. Maximieren Sie im linken Navigationsbereich den Bereich API-Hub.
3. Wählen Sie in der Liste die API und die Version aus, die Sie bearbeiten möchten.
4. Bearbeiten Sie die Spezifikation im Bearbeitungsfeld. Sie können die API-Vorgänge auch im Swagger-Feld aufrufen.
5. Optional können Sie Ihre API mit einem simulierten Server testen.
6. Speichern Sie die Änderungen als neue Version über die Schaltfläche Mehr im Swagger-Steuerfeld und klicken Sie dann auf Im API-Hub veröffentlichen. Bestätigen oder aktualisieren Sie die Version, wenn Sie dazu aufgefordert werden, und speichern Sie die Änderungen wieder im API-Hub. Die neue Version sollte in der Versionsliste für diese API in der Liste API-Hub in Cloud Code angezeigt werden.

API mit einem simulierten Server testen

Sie können Ihre API entweder mit einem lokalen simulierten Server oder einem Google Cloud-basierten simulierten Remote-Server testen. Der lokale simulierte Server ist standardmäßig installiert und verfügbar. Simulierte Google Cloud-Server müssen Sie hingegen selbst einrichten und verwalten.

Lokalen simulierten Server verwenden

Der lokale simulierte Server akzeptiert Anfragen an diese API und emuliert Antworten. Er kann nur während der aktuellen Sitzung vom aktuellen Nutzer verwendet werden. Im Gegensatz zu einem simulierten Remote-Server ist jedoch keine Einrichtung oder Verwaltung erforderlich und es fallen keine Kosten an.

Hinweis: Der lokale simulierte Server funktioniert bei der Verwendung von VS Code Remote Explorer möglicherweise nicht ordnungsgemäß. Gelegentlich kann der lokale simulierte Server nicht gestartet werden. In diesem Fall ist er nicht in der Drop-down-Liste verfügbar.

So verwenden Sie den lokalen simulierten Server:

1. Wählen Sie im Drop-down-Menü Server den lokalen simulierten Server (Entwicklungsserver) aus.
   
2. Öffnen Sie einen Pfad und klicken Sie auf Jetzt testen.
   
3. Füllen Sie alle Anfrageparameter aus und klicken Sie auf Ausführen.
   
4. Sie können Anfragen auch per curl über einen Prompt senden. Verwenden Sie die Serveradresse und den Serverport aus dem Drop-down-Menü Server.

Simulierten Remote-Server verwenden

Mit einem simulierten Remote-Server können Sie eine persistente simulierte Server-Instanz erstellen, die im Gegensatz zum lokalen simulierten Server für andere Personen in Ihrer Organisation freigegeben und verwendet werden kann, um die neue API vor der Produktionsphase zu testen. Simulierte Remote-Server können nur mit APIs verwendet werden, die im API-Hub registriert sind.

Derzeit können simulierte Remote-Server in Google Cloud erstellt werden. Simulierte Remote-Server von Google Cloud werden nicht automatisch aktualisiert, wenn Sie nach der Bereitstellung des simulierten Servers Änderungen an der API vornehmen. Warten Sie daher mit dem Hinzufügen des simulierten Servers, bis Sie die API vollständig erstellt haben.

Wenn Sie einen simulierten Remote-Server von Google Cloud bereitstellen, wird ein neuer Cloud Run-Dienst erstellt. Er erstellt mit Cloud Build ein Container-Image für den simulierten Server und lädt das Container-Image in die Cloud Artifact Registry in Ihrem Google-Projekt hoch. Sie sind für alle daraus resultierenden Kosten und die Wartung nach der Erstellung verantwortlich. Sie sind außerdem dafür verantwortlich, es zu löschen, sobald es nicht mehr benötigt wird. Weitere Informationen finden Sie unter Was ist Cloud Run?. Dienste verwalten und die Artifact Registry-Dokumentation.

Wichtig: Sobald Sie einen simulierten Remote-Server in Google Cloud erstellt haben, sind Sie für alle daraus resultierenden Kosten verantwortlich, sowie dafür, ihn zu verwalten und zu entfernen, sobald er nicht mehr benötigt wird. Unter https://cloud.google.com/run/pricing finden Sie Preisinformationen, einschließlich Informationen zu den Optionen der kostenlosen Stufe.

So stellen Sie einen simulierten Remote-Server bereit:

1. Wählen Sie im Menü Mehr Simulierten Server bereitstellen (Google Cloud)
2. Wenn Ihre API noch nicht im API-Hub registriert ist, registrieren Sie sie, wenn Sie dazu aufgefordert werden.
3. Geben Sie Details für den simulierten Remote-Server an: Projekt-ID, Servername und Region. Klicken Sie dann auf Erstellen, um den simulierten Remote-Server zu erstellen.
   Wichtig: Erstellen Sie nie mehrere simulierte Remote-Server mit demselben Namen, auch wenn Sie dies aktuell über die Benutzeroberfläche tun können.
4. Die Generierung des simulierten Remote-Servers dauert einige Minuten. Sie können den Fortschritt im Bereich OUTPUT in Google Cloud verfolgen.
5. Sobald der simulierte Remote-Server erstellt wurde, wird die URL des Remote-Servers in der Serverliste des Swagger-Steuerfelds und im Bereich OUTPUT angezeigt.
6. Wenn Sie den simulierten Server verwenden möchten, öffnen Sie einen Pfad und klicken auf Jetzt testen.
   
   
   Füllen Sie alle Anfrageparameter aus und klicken Sie auf Ausführen.
   
   
   Sie können Anfragen auch per curl über einen Prompt senden. Verwenden Sie die Serveradresse und den Serverport aus dem Drop-down-Menü Server.

So geben Sie den Zugriff auf den simulierten Server für andere Nutzer frei:

1. Weisen Sie anderen Nutzern die Rolle „Aufrufer“ für den bereitgestellten Dienst zu. Weitere Informationen finden Sie unter Entwickler authentifizieren.
2. Um eine Anfrage an den simulierten Server zu senden, müssen Nutzer der Anleitung unter Privaten Dienst testen folgen.

So verwalten Sie bereitgestellte simulierte Remote-Server:

1. Rufen Sie den API-Hub auf und suchen Sie die API, um alle Bereitstellungen für die API aufzurufen, einschließlich aller simulierten Remote-Server.
2. Über die Ressourcen-URL können Sie die Bereitstellung aufrufen und verwalten. Sie können den simulierten Server beenden, löschen oder andere Aktionen ausführen.