API-Proxy aus einer OpenAPI-Spezifikation erstellen

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Lerninhalte

In dieser Anleitung lernen Sie Folgendes:

  • Apigee API-Proxy aus einer OpenAPI-Spezifikation erstellen
  • API-Proxy mithilfe von cURL aufrufen
  • Einem bedingten Ablauf eine Richtlinie hinzufügen
  • Richtlinienaufruf mit cURL testen

Sie erfahren, wie Sie über die Apigee-UI einen Apigee API-Proxy aus einer OpenAPI-Spezifikation erstellen. Wenn Sie den API-Proxy mit einem HTTP-Client wie cURL aufrufen, sendet der API-Proxy die Anfrage an den Apigee-Mock-Zieldienst.

Informationen zur Open API-Initiative

Open API-Initiative

„Die Open API-Initiative (OAI) konzentriert sich auf das Erstellen, Entwickeln und Bewerben eines herstellerneutralen API-Beschreibungsformats, das auf der Swagger-Spezifikation basiert.” Weitere Informationen zur Open API Initiative finden Sie unter OpenAPI-Spezifikation.

Eine OpenAPI-Spezifikation verwendet ein Standardformat zur Beschreibung einer RESTful API. Eine OpenAPI-Spezifikation, im JSON- oder YAML-Format geschrieben, ist maschinenlesbar, aber auch für Nutzer leicht lesbar. In der Spezifikation sind API-Elemente wie Basispfad, Pfade und Verben, Header, Abfrageparameter, Vorgänge, Inhaltstypen, Antwortbeschreibungen usw. beschrieben. Außerdem wird eine OpenAPI-Spezifikation häufig zum Generieren einer API-Dokumentation verwendet.

Apigee-Mock-Zieldienst

Der in dieser Anleitung verwendete Apigee-Mock-Zieldienst wird bei Apigee gehostet und gibt einfache Daten zurück. Ein API-Schlüssel oder ein Zugriffstoken sind nicht erforderlich. Sie können sogar über einen Webbrowser darauf zugreifen. Klicken Sie zum Testen auf folgenden Link:

http://mocktarget.apigee.net

Der Zieldienst gibt die Begrüßung Hello, guest! zurück.

Informationen zur vollständigen Reihe von APIs, die vom simulierten Zieldienst unterstützt werden, finden Sie unter Apigee-Beispiel-APIs.

Voraussetzungen

  • Bevor Sie beginnen, müssen Sie die Schritte unter Übersicht und Voraussetzungen ausführen.
  • Eine OpenAPI-Spezifikation. In dieser Anleitung verwenden Sie die OpenAPI-Spezifikation mocktarget.yaml, in der der Apigee-Mock-Zieldienst http://mocktarget.apigee.net beschrieben ist. Weitere Informationen finden Sie unter apigee/api-platform-samples.
  • Sie müssen cURL auf Ihrem Computer installiert haben, um API-Aufrufe über die Befehlszeile oder in einem Webbrowser auszuführen.

API-Proxy erstellen

So erstellen Sie den API-Proxy aus einer OpenAPI-Spezifikation:

Apigee in der Cloud Console

  1. Rufen Sie in der Google Cloud Console die Seite Proxy-Entwicklung > API-Proxys auf.

    Zu „API-Proxys“

  2. Klicken Sie im Bereich API-Proxys auf + Erstellen.
  3. Wählen Sie im Bereich Proxy erstellen unter Proxy-Vorlage > OpenAPI-Spezifikationsvorlage die Option Reverse-Proxy (häufigste Option) aus.
  4. Rufen Sie in Ihrem Webbrowser die folgende URL auf:
    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
  5. Klicken Sie mit der rechten Maustaste auf den angezeigten Code und wählen Sie Speichern unter aus.
  6. Klicken Sie auf Speichern, um die mocktarget3.0.yaml am gewünschten Ort zu speichern.
  7. Klicken Sie im Feld OpenAPI-Spezifikationen auf die Schaltfläche Durchsuchen.
  8. Rufen Sie die Datei mocktarget3.0.yaml auf und klicken Sie auf Öffnen.
  9. Klicken Sie auf Weiter.
  10. Im Schritt Proxy-Details des Assistenten Proxy erstellen werden die Felder automatisch mit Werten ausgefüllt, die direkt aus der OpenAPI-Spezifikation extrahiert wurden.
  11. In der folgenden Tabelle werden die Standardwerte beschrieben, die mit der OpenAPI-Spezifikation bereits ausgefüllt wurden:

    Feld Beschreibung Standard
    Proxy-Name Name des API-Proxys. Beispiel: Mock-Target-API Attribut title aus der OpenAPI-Spezifikation, wobei Leerzeichen durch Bindestriche ersetzt werden.
    Basispfad Pfadkomponente, die diesen API-Proxy in der Organisation eindeutig identifiziert. Die öffentliche URL dieses API-Proxys besteht aus Ihrem externen oder internen Domainnamen und diesem Basispfad. Beispiel: http://apitest.acme.com/mock-target-api Inhalt des Feldes Name wird in Kleinbuchstaben umgewandelt.
    Beschreibung Beschreibung des API-Proxys Attribut description aus der OpenAPI-Spezifikation
    Ziel (vorhandene API) Die Ziel-URL, die im Namen dieses API-Proxys aufgerufen wird. Jede URL, auf die über das offene Internet zugegriffen werden kann, kann verwendet werden. Beispiel: http://mocktarget.apigee.net Attribut servers aus der OpenAPI-Spezifikation

    Im Folgenden finden Sie einen Auszug aus der OpenAPI-Spezifikation mit den Attributen, die zum Vorausfüllen der Felder verwendet werden.

          openapi: 3.0.0
          info:
            description: OpenAPI Specification for the Apigee mock target service endpoint.
            version: 1.0.0
            title: Mock Target API
          paths:
            /:
              get:
                summary: View personalized greeting
                operationId: View a personalized greeting
                description: View a personalized greeting for the specified or guest user.
                parameters:
                  - name: user
                    in: query
                    description: Your user name.
                    required: false
                    schema:
                      type: string
                responses:
                  "200":
                    description: Success
          ...
          servers:
            - url: http://mocktarget.apigee.net
            - url: https://mocktarget.apigee.net
          ...
          
  12. Bearbeiten Sie im Schritt Proxy-Details das Feld Beschreibung so:
    API proxy for the Apigee mock target service endpoint.
  13. Klicken Sie auf Weiter.
  14. Prüfen Sie im Schritt Workflows, ob alle Vorgänge ausgewählt sind.
  15. Klicken Sie auf Weiter.
  16. Wählen Sie im Schritt Bereitstellen eine oder mehrere Umgebungen aus und klicken Sie auf OK.
  17. Klicken Sie auf Erstellen.

Klassische Apigee-UI

  1. Wählen Sie Entwickeln > API-Proxys aus und im Bereich Proxys wählen Sie die Umgebung für den Proxy aus.
  2. Klicken Sie im Hauptfenster auf API-Proxys.

    Alternativ können Sie in der linken Navigationsleiste Entwickeln > API-Proxies auswählen.

    Klicken Sie auf „API Proxies“ auf der Landingpage

  3. Klicken Sie auf Neu erstellen.

    API-Proxy hinzufügen
  4. Klicken Sie im Assistenten Proxy erstellen auf die Option OpenAPI-Spezifikation für die Vorlage Reverse-Proxy (häufigste Option).

    Proxytyp erstellen
  5. Klicken Sie auf URL und geben Sie die folgenden Informationen ein:

    OpenAPI Spec URL: Pfad zum Rohdateninhalt auf GitHub für die OpenAPI-Spezifikation im Feld URL:

    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
  6. Klicken Sie auf Auswählen.

    Die Seite Proxy-Details im Assistenten Proxy erstellen wird angezeigt. Die Felder sind mit Werten gefüllt, die in der OpenAPI-Spezifikation definiert sind, wie in der folgenden Abbildung gezeigt.

    In der folgenden Tabelle werden die Standardwerte beschrieben, die mit der OpenAPI-Spezifikation bereits ausgefüllt wurden:

    Feld Beschreibung Standard
    Name Name des API-Proxys. Beispiel: Mock-Target-API Attribut title aus der OpenAPI-Spezifikation, wobei Leerzeichen durch Bindestriche ersetzt werden.
    Basispfad Pfadkomponente, die diesen API-Proxy in der Organisation eindeutig identifiziert. Die öffentliche URL dieses API-Proxys besteht aus Ihrem externen oder internen Domainnamen und diesem Basispfad. Beispiel: http://apitest.acme.com/mock-target-api Inhalt des Feldes Name wird in Kleinbuchstaben umgewandelt.
    Beschreibung Beschreibung des API-Proxys Attribut description aus der OpenAPI-Spezifikation
    Ziel (vorhandene API) Die Ziel-URL, die im Namen dieses API-Proxys aufgerufen wird. Jede URL, auf die über das offene Internet zugegriffen werden kann, kann verwendet werden. Beispiel: http://mocktarget.apigee.net Attribut servers aus der OpenAPI-Spezifikation

    Im Folgenden finden Sie einen Auszug aus der OpenAPI-Spezifikation mit den Attributen, die zum Vorausfüllen der Felder verwendet werden.

    openapi: 3.0.0
    info:
      description: OpenAPI Specification for the Apigee mock target service endpoint.
      version: 1.0.0
      title: Mock Target API
    paths:
      /:
        get:
          summary: View personalized greeting
          operationId: View a personalized greeting
          description: View a personalized greeting for the specified or guest user.
          parameters:
            - name: user
              in: query
              description: Your user name.
              required: false
              schema:
                type: string
          responses:
            "200":
              description: Success
    ...
    servers:
      - url: http://mocktarget.apigee.net
      - url: https://mocktarget.apigee.net
    ...
    
  7. Bearbeiten Sie auf der Seite Proxy-Details das Feld Beschreibung. Gehen Sie so vor:
    API proxy for the Apigee mock target service endpoint.
  8. Klicken Sie auf Weiter.
  9. Wählen Sie auf der Seite Allgemeine Richtlinien unter Sicherheit: Autorisierung die Option Passthrough (keine Autorisierung) aus und klicken Sie auf Weiter:

    Seite „Passthrough (keine Autorisierung)“ ist auf der Seite „Allgemeine Richtlinien“ ausgewählt.

  10. Prüfen Sie auf der Seite Workflows, ob alle Vorgänge ausgewählt sind. Proxy-Workflow erstellen
  11. Klicken Sie auf Weiter.
  12. Achten Sie darauf, dass auf der Seite Zusammenfassung unter Optionale Bereitstellung eine Umgebung ausgewählt ist, und klicken Sie auf Erstellen und bereitstellen:

    Apigee erstellt Ihren neuen API-Proxy und stellt ihn in Ihrer Umgebung bereit:

  13. Klicken Sie auf Proxy bearbeiten, um die Seite Übersicht für den API-Proxy aufzurufen.

API-Proxy testen

Sie können Ihre Mock-Target-API API mit cURL oder einem Webbrowser testen.

curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy

Dabei ist YOUR_ENV_GROUP_HOSTNAME der Hostname Ihrer Umgebungsgruppe. Weitere Informationen finden Sie unter Hostname der Umgebungsgruppe finden.

Beispiel:

curl -v -k https://apitest.acme.com/myproxy

Antwort

Sie sollten die folgende Antwort sehen:

Hello, Guest!

XML-zu-JSON-Richtlinie hinzufügen

Als Nächstes fügen Sie die XML-zu-JSON-Richtlinie dem bedingten Workflow View XML Response hinzu, der automatisch generiert wurde, als Sie den API-Proxy aus der OpenAPI-Spezifikation erstellt haben. Die Richtlinie konvertiert die XML-Antwort des Ziels in eine JSON-Antwort.

Rufen Sie zuerst die API auf, damit Sie die Ergebnisse mit denen vergleichen können, die Sie nach Hinzufügen der Richtlinie erhalten haben. Führen Sie in einem Terminalfenster den folgenden cURL-Befehl aus. Sie rufen die Ressource /xml des Zieldienstes auf, die nativ einen einfachen XML-Block zurückgibt.

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

Dabei ist YOUR ENV_GROUP_HOSTNAME der Hostname der Umgebungsgruppe. Weitere Informationen finden Sie unter Hostname der Umgebungsgruppe finden.

Antwort

Sie sollten die folgende Antwort sehen:

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

Konvertieren Sie jetzt die XML-Antwort in JSON. Fügen Sie die XML-zu-JSON-Richtlinie dem bedingten Workflow „View XML Response“ im API-Proxy hinzu.

Apigee in der Cloud Console

  1. Klicken Sie auf der Seite Mock-Ziel-API – Übersicht der Apigee-Benutzeroberfläche auf den Tab Entwickeln.

  2. „View XML Response“ auswählen

  3. Klicken Sie im linken Bereich unter Proxy-Endpunkte > Standard auf den bedingten Workflow View XML Response.
  4. Klicken Sie im linken Bereich in der Zeile Richtlinien auf die Schaltfläche +.
  5. Klicken Sie im Dialogfeld Richtlinie erstellen in das Feld Richtlinientyp wählen, scrollen Sie nach unten zu Mediation und wählen Sie XMLToJSON. Behalten Sie die Standardwerte für Anzeigename und Name bei.

  6. Klicken Sie auf Erstellen, um die Richtlinie zu erstellen.
  7. Klicken Sie in der Antwort neben dem Workflow View XML Response auf die Schaltfläche +.

    Schritt „+ auswählen“

  8. Klicken Sie im Dialogfeld Richtlinienschritt hinzufügen auf das Feld Vorhandene Richtlinie auswählen und wählen Sie XML zu JSON-1 aus.
  9. Klicken Sie auf Hinzufügen. Die XML-zu-JSON-Richtlinie wird auf die Antwort angewendet.

    XML-to-JSON-Richtlinie im Workflow

    Klicken Sie auf Zum Code-Editor wechseln, um den Code für den bedingten Workflow View XML Response aufzurufen.

  10. Klicken Sie auf Speichern.

Klassische Apigee-UI

  1. Klicken Sie auf der Seite Mock-Ziel-API – Übersicht der Apigee-Benutzeroberfläche auf den Tab Entwickeln.

    Tab „Entwickler“
  2. Klicken Sie im linken Navigationsbereich unter Proxy-Endpunkte > Standard auf den bedingten Workflow View XML Response.

    „View XML Response“ auswählen
  3. Klicken Sie auf die Schaltfläche + Schritt, die der Antwort für den Workflow entspricht.

    „+ Schritt“ auswählen

    Im Dialogfeld Schritt hinzufügen wird eine Kategorienliste aller Richtlinien angezeigt, die Sie hinzufügen können.

  4. Scrollen Sie zur Kategorie Mediation und wählen Sie XML zu JSON aus.

    Dialogfeld „Schritt hinzufügen“
  5. Behalten Sie die Standardwerte für Anzeigename und Name bei.
  6. Klicken Sie auf Hinzufügen. Die XML-zu-JSON-Richtlinie wird auf die Antwort angewendet.

    XML-to-JSON-Richtlinie im Workflow
  7. Klicken Sie auf Speichern.

Nachdem Sie die Richtlinie hinzugefügt haben, rufen Sie die API anhand von cURL noch einmal auf. Beachten Sie, dass Sie immer noch dieselbe /xml-Ressource aufrufen. Der Zieldienst gibt weiterhin seinen XML-Block zurück, die Richtlinie im API-Proxy konvertiert nun aber die Antwort in das JSON-Format. Führen Sie folgenden Aufruf aus:

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

Dabei ist YOUR ENV_GROUP_HOSTNAME der Hostname der Umgebungsgruppe. Weitere Informationen finden Sie unter Hostname der Umgebungsgruppe ermitteln.

Die XML-Antwort wird in das JSON-Format konvertiert:

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}