Anwendungsentwicklung mit der SAP BTP Edition des ABAP SDK for Google Cloud

Dieses Dokument enthält nützliche Informationen und Ressourcen, mit denen Sie SAP-Anwendungen mit der SAP BTP-Edition des ABAP SDK for Google Cloud entwickeln können.

Dieses Dokument richtet sich an SAP ABAP-Entwickler.

Eine vollständige Liste der Clientbibliotheken, die die SAP BTP-Edition des ABAP SDK for Google Cloud bereitstellt, finden Sie unter ABAP SDK for Google Cloud-Clientbibliotheken.

Einzelfenster der Interaktion

Jede Google Cloud API, die im ABAP SDK for Google Cloud aktiviert ist, wird durch eine ABAP-Klasse dargestellt, die im Paket /GOOG/CLIENT enthalten ist. Eine ABAP-Klasse besteht aus mehreren öffentlichen Methoden und jede dieser öffentlichen Methoden entspricht einer Google Cloud API-Methode. Jede öffentliche Methode besteht außerdem aus den Parametern IMPORTING und EXPORTING. Eine ABAP-Klasse enthält auch benutzerdefinierte Datentypen, mit denen die Parameter IMPORTING und EXPORTING erstellt und zugeordnet werden können. Diese benutzerdefinierten Datentypen ordnen sich den API-Schemadefinitionen zu.

Bei jeder Interaktion mit einer Google Cloud-Ziel-API dient die entsprechende ABAP-Klasse als einziger Interaktionspunkt. Wir bezeichnen dieses Konzept als Einzelfenster der Interaktion, das alle zugrunde liegenden Komplexitäten der Interaktion mit einer Google Cloud API abschirmt und eine vereinfachte Benutzeroberfläche darstellt. Dank dieser vereinfachten Schnittstelle können Sie sich auf die Entwicklung der mit dem SDK entwickelten Geschäftslösungen konzentrieren, ohne sich um die zugrunde liegenden SDK-Features kümmern zu müssen.

Interaktionsablauf

Für den Aufruf einer API-Methode verfügen Sie über den folgenden Interaktionsablauf:

1. Verbinden Sie sich mit einer API.
2. Erstellen Sie eine Eingabeanfrage mit den ABAP-Typen.
3. Rufen Sie eine API-Methode auf.
4. Parsen Sie Fehler und Ausnahmen.
5. Lesen Sie die Antwort mit den ABAP-Typen.

API-Client-Stub

Eine typische API-Client-Stub-Klasse besteht aus den folgenden Abschnitten:

• Die ABAP-Typen, die den API-Schemas zugeordnet sind. Sie verwenden ABAP-Typen, um eine Eingabeanfrage zu erstellen und die Antwort zu parsen.
• Die Konstanten und Attribute für die interne oder externe Nutzung.
• Die API-Methoden für die Interaktion mit API-Ressourcen.

Features

Das ABAP SDK for Google Cloud enthält die folgenden Features:

• HTTP-Kommunikation: das SDK stellt eine HTTP-Verbindung zu den API-Endpunkten her.
• Anfrage-Marshaling: das SDK konvertiert Daten in ABAP-Typen in JSON-Nutzlast, die als Anfragetext gesendet wird.
• Verarbeitung von Fehlern und Ausnahmen: das SDK verarbeitet die von der API zurückgegebenen Rückgabecodes und Fehlermeldungen und löst gegebenenfalls Ausnahmen aus.
• Unmarshalling-Antwort: das SDK konvertiert die JSON-Nutzlast im Antworttext in die entsprechenden ABAP-Typen zurück.
• Lokales Fehler-Logging: das SDK protokolliert Fehlermeldungen mithilfe des Logging-Frameworks.

API-Design und Google API Explorer

Von Google veröffentlichte APIs folgen einem ressourcenorientierten Design. Weitere Informationen zum API-Design von Google finden Sie in der API-Designanleitung.

Das ABAP SDK for Google Cloud ermöglicht die Einbindung in die von Google veröffentlichten REST-basierten APIs.

Der Google API Explorer ist ein Tool, mit dem Sie Google Cloud API-Methoden testen können, ohne Code zu schreiben. Verwenden Sie dieses Tool, um die APIs und die erforderlichen Eingabeparameter zu untersuchen, die Sie an die entsprechenden ABAP-Methoden übergeben möchten.

Codekonstrukte

Erläutert die Codekonstrukte, die Sie zum Erstellen Ihrer ABAP-Programme mit dem ABAP SDK for Google Cloud verwenden.

Konstruktor

Zuerst instanziieren Sie die API-Klasse, die Sie verwenden möchten. Der Konstruktor jeder API-Klasse hat ein ähnliches Muster wie im folgenden Beispiel:

    METHODS constructor
      IMPORTING
        !iv_key_name   TYPE /goog/keyname OPTIONAL "Google Cloud Key Name
        !iv_log_obj    TYPE balobj_d OPTIONAL      "Application log: Object name
        !iv_log_subobj TYPE balsubobj OPTIONAL.    "Application log: Subobject
      RAISING
        /goog/cx_sdk .                 "Exception Classes

Parameter importieren

In der folgenden Tabelle werden die Importparameter eines Methodenkonstruktors erläutert:

API-Methode

Beim ressourcenorientierten Design von Google Cloud APIs ist eine API-Methode eine Aktion, die für eine von der API veröffentlichte Ressource ausgeführt werden kann.

Wenn beispielsweise Topics eine Ressource ist, die von der Pub/Sub API veröffentlicht wird, dann ist topics.get eine API-Methode, die eine Aktion für die Ressource Topics darstellt, um die Konfiguration eines Themas abzurufen.

Informationen zum Zuordnen einer ABAP-Klassenmethode zu einer API-Methode finden Sie in der Methodenbeschreibung, die dem folgenden Muster folgt:<resource>.<method_verb>.

Die Methodenbeschreibung für eine Pub/Sub-Methode lautet beispielsweise pubsub.projects.topics.get.

• projects.topics: der Ressourcenname.
• get: die Methodenaktion.

Der Name einer ABAP-Methode, die einer API-Aktion zugeordnet ist, folgt dem folgenden Muster:<method_verb>_<resource>.

Ein ABAP-Methodenname für Pub/Sub lautet beispielsweise: GET_TOPICS.

• GET: die Methodenaktion.
• TOPICS: der Ressourcenname.

Eine ABAP-Methode besteht aus den folgenden Abschnitten, die den REST API-Methoden zugeordnet sind:

Parameter importieren

Eine API-Methode kann die folgenden Importparameter haben. Diese Parameter sind optional. Sie können die Parameter basierend auf den Anforderungen einer API-Methode übergeben, die Sie verwenden müssen.

Parameter exportieren

Eine API-Methode unterstützt folgende Exportparameter:

Klassentyp

Google Cloud APIs verwenden JSON als primäres Format für den Datenaustausch. Das ABAP SDK for Google Cloud bietet ABAP-Typen, die dem JSON-Schema zugeordnet sind, das von den Google Cloud APIs erwartet wird.

Diese ABAP-Typen und die zugehörigen Tabellentypen sind als Klassentypen in jeder vom SDK bereitgestellten API-Klasse verfügbar.

Das folgende Beispiel zeigt den Klassentyp für die Pub/Sub API-Klasse /GOOG/CL_PUBSUB_V1.

Die Beschreibung des Klassentyps TY_041 unter /GOOG/CL_PUBSUB_V1 wird der REST-Ressource Topic zugeordnet, die als JSON-Nutzlast an die Methode CREATE_TOPICS übergeben wird.

ABAP Doc-Kommentare werden allen Client-API-Klassen hinzugefügt. Wenn Sie ABAP-Entwicklertools für SAP NetWeaver (ADT) für die Entwicklung verwenden, enthalten diese Kommentare Beschreibungen der Klassentypen.

API-Rückgabecodes, Fehler und Ausnahmen

Wenn beim Aufruf der API-Methode der ABAP-Klasse ein Fehler auftritt, übergibt das ABAP SDK for Google Cloud die Fehlerinformationen mithilfe der SDK-Exportparameter oder durch Auslösen von Ausnahmen an das aufrufende Programm.

API-Rückgabecode und Fehler

Google Cloud APIs verwenden ein Fehlermodell, das eine konsistente Nutzererfahrung über verschiedene APIs hinweg bietet. Wenn eine Google Cloud API-Methode aus dem SDK aufgerufen wird, enthalten die folgenden Parameter den Rückgabecode und die Nachrichten der API:

• ev_ret_code: Rückgabe- oder Fehlercode in der Antwort.

• ev_error_text: Fehlermeldung in der Antwort, falls vorhanden.

• es_raw: Rohfehlerantwort, wenn ein API-Methodenaufruf fehlgeschlagen ist.

Verwenden Sie die Methode IS_SUCCESS, um den Status eines API-Aufrufs zu prüfen. Sie können den Wert von ev_ret_code verwenden, um festzustellen, ob ein API-Aufruf erfolgreich war. Falls ev_ret_code = 2XX zutrifft, gilt der Methodenaufruf im Allgemeinen als erfolgreich. Bei allen anderen Werten wird der Methodenaufruf als nicht erfolgreich eingestuft.

IF lo_client->is_success( ev_ret_code ).
   "Success: Implement custom code
   ELSE
   "Handle the HTTP error status code
ENDIF.

Für einige Google Maps Platform APIs gibt die API einen HTTP-Erfolgsstatuscode 2XX mit einer Fehlermeldung und einem Fehlerstatus zurück, wenn Sie eine API mit ungültigen Eingaben aufrufen, anstatt eines HTTP-Fehlerstatuscodes (4XX oder 5XX). Diese Fehlermeldung und der Fehlerstatus in der API-Antwort können Ihnen bei der Fehlersuche helfen und ungültige Eingaben beheben.

Prüfen Sie für solche Google Maps Platform APIs zusätzlich zum Rückgabecode ev_ret_code die Fehlermeldung und den Fehlerstatus, die in der API-Antwort zurückgegeben werden. Rufen Sie dazu die Methode IS_STATUS_OK nach der API auf. Das folgende Snippet zeigt ein Beispiel für die Verwendung der Methode IS_STATUS_OK:

IF lo_client->is_status_ok( ).
  "Success: Implement custom code
  ELSE
  "Handle the HTTP error status code
ENDIF.

Der Parameter es_err_resp enthält zusätzliche Informationen zum Fehler. In der folgenden Tabelle werden die Felder im Parameter es_err_resp erläutert.

Umgang mit Fehlern, die von Google Cloud APIs zurückgegeben werden

Verwenden Sie die folgende Anleitung zur Behandlung der von Google Cloud APIs zurückgegebenen Fehler:

• Häufig auftretende Fehlercodes: Informationen zu häufigen Fehlern, die von Google Cloud APIs zurückgegeben werden, sowie deren Ursache finden Sie unter Fehlercodes.

• Detaillierten Fehler erfassen: Verwenden Sie den Exportparameter es_raw aus den SDK-Klassenmethoden und ordnen Sie diesen Parameter zu, um detaillierte Fehlerinformationen mit dem ABAP SDK für Google Cloud für eine Variable vom Typ String zu erfassen. Diese Variable enthält eine JSON-Antwort mit detaillierten Fehlermeldungen und bestimmten Verstößen, die von den APIs auftreten.

• Detaillierte Fehler ansehen: Verwenden Sie eine der folgenden Methoden, um detaillierte Fehlerinformationen aufzurufen:

  • Debugger: Rufen Sie den Inhalt der Variablen auf, die die JSON-Antwort im ABAP-Debugger-Tool enthält, um weitere Analysen durchzuführen.

  • SAP-GUI: Verwenden Sie die ABAP-Klasse cl_demo_output=>display( lv_response ) zur visuellen Darstellung des Fehlers in einem Berichtsprogramm. Verwenden Sie die ABAP-Klasse cl_demo_output=>display_json( lv_response ), wenn Sie die API-Methoden in einem Berichtsprogramm verwenden und die Programmausführung im Vordergrundmodus erfolgt.

    Das folgende Code-Snippet zeigt, wie die API-Antwort bei einem Fehler angezeigt wird:

    DATA lv_response  TYPE string,
      TRY.
          lo_translate = NEW #( iv_key_name = 'DEMO_TRANSLATE' ).
          lo_translate->translate_translations
            EXPORTING
              is_input    = ls_input
            IMPORTING
              es_raw      = lv_response
              es_output   = ls_output
              ev_ret_code = lv_ret_code
              ev_err_text = lv_err_text
              es_err_resp = ls_err_resp.
          IF lo_translate->is_error( lv_ret_code ) = abap_true.
            " Display API response in case of an error
            cl_demo_output=>display_json( lv_response ).
          ENDIF.
        CATCH /goog/cx_sdk INTO lo_exception.
          lv_err_text = lo_exception->get_text( ).
      ENDTRY.
    

• API-spezifische Dokumentation: Einige Google Cloud APIs enthalten detaillierte Fehlerinformationen und Anleitungen zur Fehlerbehebung in der jeweiligen Dokumentation. Informationen zum Beheben eines Fehlers im Zusammenhang mit einer API finden Sie in der Dokumentation zu dieser API, z. B. Pub/Sub, Document AI und Cloud Storage.

Ausnahmen

Wenn während eines API-Methodenaufrufs ein unerwarteter Fehler auftritt, z. B. eine falsche SDK-Konfiguration oder ein HTTP-Kommunikationsfehler, löst das SDK eine Klassenausnahme vom Typ /GOOG/CX_SDK aus. Sie müssen diese Ausnahme im Code abfangen und eine entsprechende Fehlerbehandlungslogik schreiben.

Sie können die Fehlermeldung abrufen, indem Sie die Methode get_text der Ausnahmeklasse aufrufen. Die von der Ausnahmeklasse zurückgegebene Fehlermeldung hat folgendes Format:

/GOOG/MSG : Return_Code - Error_Message

Die Ursache des Fehlers und der Schritte zur Lösung hängt vom Wert von Return_Code ab.

Typische Fehlermeldungen, die im ABAP SDK for Google Cloud ausgelöst werden, sowie deren Lösung finden Sie in der Anleitung zur Fehlerbehebung.

Logging

Mit der SAP BTP-Version des ABAP SDK for Google Cloud können Sie Fehlermeldungen mit einem eingebetteten Logging-Framework protokollieren. Das Logobjekt /GOOG/LOG_OBJECT und das Unterobjekt /GOOG/LOG_SUBOBJECT werden mit dem SDK geliefert, mit dem Sie Ihre Standard-Logkonfiguration erstellen können. Weitere Informationen zum Erstellen einer Standard-Logkonfiguration finden Sie unter Logging konfigurieren.

Sie können Anwendungslogs mit der App Google SDK:Anwendungslogs anzeigen aufrufen. Weitere Informationen finden Sie unter Logs ansehen.

Datentypzuordnung

Die folgende Tabelle enthält eine vollständige Liste der type und format-Werte, die vom Google APIs Discovery Service und dem entsprechenden ABAP-Datentyp unterstützt werden.

Weitere Informationen zu den vom Google APIs Discovery Service unterstützten type- und format-Werten finden Sie unter Zusammenfassung von Typen und Formaten.

Serialisierung und Deserialisierung von API-Anfragen und -Antworten

Standardmäßig übernimmt die SAP BTP-Version des ABAP SDK for Google Cloud das Marshalling und Unmarshalling von API-Anfragen und -Antworten. Jede ABAP-Klasse für eine Google Cloud API hat eingebettete ABAP-Typen, um die Eingabe und Ausgabe der Methoden zu bilden. Zur Implementierung einer benutzerdefinierten Transformation von Anfrage und Antwort können Sie den Optimierungspunkt mit SAP BAdI-Definitionen (Business Add In) verwenden, die mit dem SDK geliefert werden.

Benutzerdefinierte Transformation implementieren

Der mit dem SDK gelieferte Optimierungsspot /GOOG/ES_TRANSFORM_JSON enthält die folgenden BAdI-Definitionen:

• /GOOG/BADI_SERIALIZE_JSON: zum Implementieren der benutzerdefinierten Serialisierungslogik.
• /GOOG/BADI_DESERIALIZE_JSON: zum Implementieren der benutzerdefinierten Deserialisierungslogik.

Sie können eine spezifische Transformationslogik in Implementierungen dieser BAdIs schreiben. Die Schnittstellen dieser BAdIs haben IV_METHOD_NAME als Importparameter. Mit diesem Parameter trennen Sie die Transformationslogik für jede API und API-Methode mithilfe von IF….ENDIF-Blöcken. Legen Sie im Implementierungsblock den Exportparameter EV_HANDLED auf X fest.

So implementieren Sie die benutzerdefinierte Transformation:

1. Erstellen Sie für /GOOG/BADI_SERIALIZE_JSON eine Optimierungsimplementierung:

   • Zur Transformation von API-Anfragen erstellen Sie eine Implementierung für BAdI /GOOG/BADI_SERIALIZE_JSON mit einer Implementierungsklasse.
   • Zum Transformieren von API-Antworten erstellen Sie eine Implementierung für BAdI /GOOG/BADI_DESERIALIZE_JSON mit einer Implementierungsklasse.

2. Ermitteln Sie die Methoden-ID der API-Methode, für die Sie die Transformation schreiben müssen. Die Methoden-ID ist eine Verkettung aus folgenden Elementen:

   • Der Wert der Klassenattributkonstante C_SERVICE_NAME.
   • Das Zeichen #.
   • Die Beschreibung der API-Klassenmethode, für die Sie die Transformation implementieren müssen.

   Wenn Sie beispielsweise Transformationen zum Veröffentlichen von Nachrichten in einem Pub/Sub-Thema schreiben möchten, lautet die Methoden-ID pubsub:v1#pubsub.projects.topics.publish.

3. Bei der Methodenimplementierung des BAdI:

   1. Schreiben Sie als Methoden-ID Ihre benutzerdefinierte Transformation unter einem IF….ENDIF block.

   2. Legen Sie für den Exportparameter EV_HANDLED den Wert X fest.

      Wenn EV_HANDLED nicht auf X eingestellt ist, wird die Standard-Marshalling- und Unmarshalling-Logik des SDK angewendet.

4. Markieren Sie den API State der implementierenden Klasse als Use System-Internally (Contract C1). Die benutzerdefinierte Transformationslogik wird während der Laufzeit aufgerufen. Die mit dem SDK gelieferte Standardlogik zur Serialisierung und Deserialisierung wird übersprungen.

Namespace

Der gesamte von Google bereitgestellte Code wird im reservierten Namespace /GOOG/ abgelegt.

Referenzarchitekturen

Mithilfe der Referenzarchitekturen können Sie das ABAP SDK for Google Cloud kennenlernen und herausfinden, wie das SDK Ihre SAP-Anwendungslandschaft innovativ gestalten kann. Sie können das SDK verwenden, um Vertex AI für erweiterte KI- und ML-Funktionen und andere Google Cloud-Dienste wie BigQuery, Pub/Sub, Cloud Storage und viele mehr zu integrieren. Weitere Informationen finden Sie unter Referenzarchitekturen für das ABAP SDK for Google Cloud.

Support kontaktieren

Wenn Sie Hilfe bei der Behebung von Problemen mit dem ABAP SDK für Google Cloud benötigen, gehen Sie so vor:

• Weitere Informationen finden Sie im Leitfaden zur Fehlerbehebung für ABAP SDK für Google Cloud.

• In den Cloud-Foren können Sie Ihre Fragen stellen und über die ABAP SDK für Google Cloud mit der Community sprechen.

• Erfassen Sie alle verfügbaren Diagnoseinformationen und wenden Sie sich an Cloud Customer Care. Informationen zur Kontaktaufnahme mit Customer Care finden Sie unter Support für SAP in Google Cloud.