Importieren von SAP OData-Metadaten als API

GILT FÜR: Alle API Management-Ebenen

In diesem Artikel wird gezeigt, wie Sie einen OData-Dienst mithilfe seiner Metadatenbeschreibung importieren. In diesem Artikel dient SAP Gateway Foundation als Beispiel.

In diesem Artikel führen Sie Folgendes durch:

• Abrufen von OData-Metadaten aus Ihrem SAP-Dienst
• Importieren von OData-Metadaten in API Management, entweder direkt oder nach der Konvertierung in eine OpenAPI-Spezifikation
• Vollständige API-Konfiguration
• Testen der API im Azure-Portal

Voraussetzungen

• Eine bestehende API Management-Instanz. Erstellen Sie eine, falls nicht schon geschehen.

• Ein SAP-System und -Dienst, die als OData v2 oder v4 verfügbar gemacht sind.

• Wenn Ihr SAP-Back-End ein selbstsigniertes Zertifikat verwendet (zu Testzwecken), müssen Sie möglicherweise die Überprüfung der Vertrauenskette für SSL deaktivieren. Konfigurieren Sie dazu ein Back-End in Ihrer API Management-Instanz:

  1. Wählen Sie im Azure-Portal unter APIs die Option Back-Ends>+ Hinzufügen aus.
  2. Fügen Sie eine benutzerdefinierte URL hinzu, die auf den SAP-Back-End-Dienst verweist.
  3. Deaktivieren Sie die Optionen Validate certificate chain (Zertifikatkette überprüfen) und Validate certificate name (Zertifikatnamen überprüfen).

  Hinweis

  Verwenden Sie für Produktionsszenarien die geeigneten Zertifikate für die End-to-End-SSL-Überprüfung.

Abrufen von OData-Metadaten aus Ihrem SAP-Dienst

Rufen Sie die Metadaten-XML aus Ihrem SAP-Dienst mithilfe einer der folgenden Methoden ab. Wenn Sie planen, die Metadaten-XML in eine OpenAPI-Spezifikation zu konvertieren, speichern Sie die Datei lokal.

• Verwenden Sie den SAP Gateway-Client (Transaktion /IWFND/GW_CLIENT), oder
• Führen Sie einen direkten HTTP-Aufruf aus, um die XML abzurufen: http://<OData server URL>:<port>/<path>/$metadata

Navigieren zur API Management-Instanz

1. Suchen Sie im Azure-Portal nach API Management-Dienste, und wählen Sie diese Option aus.

   

2. Wählen Sie auf der Seite API Management-Dienste Ihre API Management-Instanz aus.

   

Importieren der API in API Management

Wählen Sie eine der folgenden Methoden aus, um Ihre API in API Management zu importieren: Importieren Sie die Metadaten-XML direkt als OData-API, oder konvertieren Sie die Metadaten-XML in eine OpenAPI-Spezifikation.

OData-Metadaten

Importieren von OData-Metadaten

1. Wählen Sie im linken Menü APIs> + API hinzufügen aus.

2. Wählen Sie unter Aus Definition erstellen die Option OData aus.

   

3. Geben Sie API-Einstellungen ein. Sie können Ihre Einstellungen später aktualisieren, indem Sie zur Registerkarte Einstellungen der API wechseln.

   1. Geben Sie in der OData-Spezifikation eine URL für einen OData-Metadatenendpunkt ein. Das ist in der Regel die URL zum Dienststamm, die mit „/$metadata“ angefügt wird. Alternativ können Sie eine lokale OData-XML-Datei zum Importieren auswählen.

   2. Geben Sie die verbleibenden Einstellungen ein, um Ihre API zu konfigurieren. Diese Einstellungen werden im Tutorial Importieren und Veröffentlichen Ihrer ersten API erläutert.

4. Klicken Sie auf Erstellen.

   Die API wird der Liste APIs hinzugefügt. Die Entitätssätze und Funktionen, die in der OData-Metadatenbeschreibung verfügbar gemacht werden, werden auf der Registerkarte Entitätenmenge und Funktionen der API angezeigt.

   

Aktualisieren des OData-Schemas

Sie können auf einen Editor im Portal zugreifen, um das OData-Schema Ihrer API anzuzeigen. Wenn sich die API ändert, können Sie das Schema in API Management auch aus einer Datei oder einem OData-Dienstendpunkt aktualisieren.

1. Navigieren Sie im Portal zu Ihrer API Management-Instanz.

2. Wählen Sie im linken Menü APIs> Ihre OData-API aus.

3. Wählen Sie auf der Registerkarte Entitätssätze und Funktionen das Kontextmenü (...) neben einem Entitätssatz oder einer Funktion aus, und wählen Sie Bearbeiten aus.

   

4. Überprüfen Sie das Schema. Wenn Sie es aktualisieren möchten, wählen Sie Aus Datei aktualisieren oder Schema vom Endpunkt aktualisieren aus.

   

Testen der OData-API

1. Wählen Sie im linken Menü APIs> Ihre OData-API aus.

2. Wählen Sie auf der Registerkarte Entitätssätze und Funktionen das Kontextmenü (...) neben einem Entitätssatz oder einer Funktion aus, und wählen Sie Testen aus.

   

3. Geben Sie in der Testkonsole Vorlagenparameter, Abfrageparameter und Header für Ihren Test ein, und wählen Sie Testen aus. Erfahren Sie mehr über das Testen einer API im Portal.

Schützen Ihrer OData-API

Schützen Sie Ihre OData-API, indem Sie sowohl vorhandene Authentifizierungs- und Autorisierungsrichtlinien als auch eine OData-Validierungsrichtlinie anwenden, um sich gegen Angriffe durch OData-API-Anforderungen abzusichern.

Tipp

Konfigurieren Sie im Portal auf der Registerkarte API-Richtlinien Richtlinien für Ihre OData-API.

OpenAPI-Spezifikation

Konvertieren von OData-Metadaten in OpenAPI-JSON

1. Konvertieren Sie den OData-XML-Code in das OpenAPI-JSON-Format. Verwenden Sie je nach Metadaten-XML ein OASIS-Open-Source-Tool für OData v2 oder OData v4.

   Im Folgenden finden Sie einen Beispielbefehl zum Konvertieren von OData v2-XML für den Testdienst epm_ref_apps_prod_man_srv:

   odata-openapi -p --basePath '/sap/opu/odata/sap/epm_ref_apps_prod_man_srv' \
    --scheme https --host <your IP address>:<your SSL port> \
    ./epm_ref_apps_prod_man_srv.xml
   

   Hinweis

   • Zu Testzwecken mit einer einzelnen XML-Datei können Sie einen webbasierten Konverter verwenden, der auf dem Open-Source-Tool basiert.
   • Mit dem Tool oder dem webbasierten Konverter ist die Angabe von <IP-Adresse>:<Port> Ihres SAP OData-Servers optional. Alternativ können Sie diese Informationen später in Ihrer generierten OpenAPI-Spezifikation oder nach dem Importieren in API Management hinzufügen.

2. Speichern Sie die openapi-spec.json-Datei lokal für den Import in API Management.

Importieren und Veröffentlichen einer Back-End-API

1. Wählen Sie im Seitennavigationsmenü im Abschnitt APIs die Option APIsaus.

2. Wählen Sie unter Neue Definition erstellen die Option OpenAPI-Spezifikation aus.

   

3. Klicken Sie auf Datei auswählen, und wählen Sie die Datei openapi-spec.json aus, die Sie in einem vorherigen Schritt lokal gespeichert haben.

4. Geben Sie API-Einstellungen ein. Sie können die Werte während der Erstellung festlegen oder später über die Registerkarte Einstellungen konfigurieren.

   • Wir empfehlen, im API-URL-Suffix denselben URL-Pfad wie im ursprünglichen SAP-Dienst zu verwenden.

   • Weitere Informationen zu API-Einstellungen finden Sie im Tutorial Importieren und Veröffentlichen Ihrer ersten API.

5. Klicken Sie auf Erstellen.

Hinweis

Die Einschränkungen beim API-Import sind in einem anderen Artikel dokumentiert.

Vollständige API-Konfiguration

Fügen Sie der API, die Sie importiert haben, die folgenden drei Vorgänge hinzu.

• GET /$metadata

  Vorgang	BESCHREIBUNG	Weitere Konfiguration des Vorgangs
  GET /$metadata	Ermöglicht API Management, den $metadata-Endpunkt zu erreichen, der für die Clientintegration in den OData-Server erforderlich ist. Dieser erforderliche Vorgang ist nicht in der OpenAPI-Spezifikation enthalten, die Sie generiert und importiert haben.	Fügen Sie eine 200 OK-Antwort hinzu.

  

• HEAD /

  Vorgang	BESCHREIBUNG	Weitere Konfiguration des Vorgangs
  HEAD /	Ermöglicht dem Client bei Bedarf den Austausch von Tokens für die siteübergreifende Anforderungsfälschung (Cross Site Request Forgery, CSRF) mit dem SAP-Server. SAP ermöglicht auch den CSRF-Tokenaustausch mithilfe des GET-Verbs. Der CSRF-Tokenaustausch wird in diesem Artikel nicht behandelt. Einen beispielhaften Richtlinienausschnitt für API Management zum Brokern des Tokenaustauschs finden Sie hier.	–

  

• GET /

  Vorgang	BESCHREIBUNG	Weitere Konfiguration des Vorgangs
  GET /	Aktiviert die Richtlinienkonfiguration im Dienststammverzeichnis.	Konfigurieren Sie die folgende Richtlinie für einen eingehenden Rewrite-URI, um an Anforderungen, die an das Dienststammverzeichnis weitergeleitet werden, einen nachstehenden Schrägstrich anzufügen: <rewrite-uri template="/" copy-unmatched-params="true" /> Diese Richtlinie beseitigt potenzielle Mehrdeutigkeiten von Anforderungen mit oder ohne nachstehende Schrägstriche, die von einigen Back-Ends unterschiedlich behandelt werden.

  

Konfigurieren Sie außerdem die Authentifizierung bei Ihrem Back-End mithilfe einer geeigneten Methode für Ihre Umgebung. Beispiele hierzu finden Sie unter API Management-Authentifizierungs- und -Autorisierungsrichtlinien.

Testen der API

1. Navigieren Sie zu Ihrer API Management-Instanz.

2. Wählen Sie im Seitennavigationsmenü im Abschnitt APIs die Option APIsaus.

3. Wählen Sie unter Alle APIs Ihre importierte API aus.

4. Wählen Sie die Registerkarte Test aus, um auf die Testkonsole zuzugreifen.

5. Wählen Sie einen Vorgang aus, geben Sie alle erforderlichen Werte ein, und wählen Sie Senden aus.

   Testen Sie beispielsweise den GET /$metadata-Aufruf, um die Konnektivität mit dem SAP-Back-End zu überprüfen.

6. Zeigen Sie die Antwort an. Zur Problembehandlung führen Sie eine Ablaufverfolgung des Aufrufs durch.

7. Beenden Sie die Testkonsole, wenn die Tests abgeschlossen sind.

Produktionsüberlegungen

• Informationen zum Integrieren von API Management in ein SAP Gateway finden Sie in diesem Beispiel für ein solches End-to-End-Szenario.
• Steuern des Zugriffs auf ein SAP-Back-End mittels API Management-Richtlinien. Wenn die API beispielsweise als OData-API importiert wird, verwenden Sie die Richtlinie zum Überprüfen der OData-Anforderung. Weitere Informationen finden Sie in den Richtlinienausschnitten für die SAP-Prinzipalweitergabe und das Abrufen eines X-CSRF-Tokens.
• Anleitungen zum Bereitstellen, Verwalten und Migrieren von APIs im großen Stil finden Sie unter:
  • Automatisierte API-Bereitstellungen mit APIOps
  • CI/CD für API Management mittels Azure Resource Manager-Vorlagen.

Zugehörige Themen

• Einschränkungen beim API-Import
• Importieren einer OpenAPI-Spezifikation
• Importieren einer SOAP-API
• Importieren einer SOAP-API und Konvertieren dieser in REST
• Importieren einer App Service-API
• Importieren einer Container-App-API
• Importieren einer WebSocket-API
• Importieren einer GraphQL-API
• Importieren eines GraphQL-Schemas und Einrichten von Feldauflösern
• Importieren einer Azure Functions-App als API
• Importieren einer Logik-App als API
• Tutorial: Integrieren von API Management in Service Fabric in Azure
• Importieren einer Azure OpenAI-API
• Importieren einer OData-API
• Importieren von SAP OData-Metadaten
• Importieren einer gRPC-API
• Bearbeiten von APIs