Développement d'applications avec l'édition SAP BTP du SDK ABAP pour Google Cloud

Ce document fournit des informations et des ressources utiles pour vous aider à développer des applications SAP à l'aide de l'édition SAP BTP du SDK ABAP pour Google Cloud.

Ce document est destiné aux développeurs SAP ABAP.

Pour obtenir la liste complète des bibliothèques clientes fournies par l'édition édition SAP BTP du SDK ABAP pour Google Cloud, consultez la page Bibliothèques clientes du SDK ABAP pour Google Cloud.

Fenêtre d'interaction unique

Chaque API Google Cloud activée dans le SDK ABAP pour Google Cloud est représentée par une classe ABAP contenue dans le package /GOOG/CLIENT. Une classe ABAP comprend plusieurs méthodes publiques, qui correspondent chacune à une méthode API Google Cloud. Chaque méthode publique inclut en outre des paramètres IMPORTING et EXPORTING. Une classe ABAP contient également des types de données personnalisés, qui peuvent être utilisés pour créer et mapper les paramètres IMPORTING et EXPORTING. Ces types de données personnalisés sont mappés aux définitions de schéma d'API.

Pour chaque interaction avec une API Google Cloud cible, sa classe ABAP correspondante sert de point d'interaction unique. Nous appelons ce concept fenêtre d'interaction unique. Celle-ci protège toutes les complexités sous-jacentes liées à l'interaction avec une API Google Cloud et présente une interface simplifiée. Cette interface simplifiée vous permet de vous concentrer sur les solutions d'entreprise développées à l'aide du SDK, sans vous soucier des fonctionnalités sous-jacentes du SDK.

Fenêtre d'interaction unique

Flux d'interaction

Pour appeler une méthode API, vous disposez du flux d'interaction suivant :

  1. Se connecter à une API
  2. Créer une requête d'entrée à l'aide des types ABAP
  3. Appeler une méthode API
  4. Analyser les erreurs et les exceptions
  5. Lire la réponse à l'aide des types ABAP

Interaction des développeurs

Bouchon de client API

Une classe de bouchon de client API comprend généralement les sections suivantes :

  • Types ABAP mappés aux schémas d'API vous permettant de créer une requête d'entrée et d'analyser la réponse
  • Constantes et attributs pour une utilisation interne ou externe
  • Méthodes API pour interagir avec les ressources d'API

Structure des classes

Fonctionnalités

Le SDK ABAP pour Google Cloud inclut les fonctionnalités suivantes :

  • Communication HTTP : le SDK établit une connexion HTTP avec les points de terminaison de l'API.
  • Marshalling des requêtes : le SDK convertit les données de type ABAP en charge utile JSON, qui est envoyée en tant que corps de la requête.
  • Gestion des erreurs et des exceptions : le SDK gère les codes et les messages d'erreur renvoyés par l'API et génère des exceptions, le cas échéant.
  • Annulation du marshalling de la réponse : le SDK reconvertit la charge utile JSON dans le corps de la réponse en types ABAP correspondants.
  • Journalisation locale des erreurs : le SDK consigne les messages d'erreur à l'aide du framework de journalisation.

Conception d'API et Google API Explorer

Les API publiées par Google suivent une conception orientée ressources. Pour en savoir plus sur la conception des API Google, consultez le guide de conception d'API.

Le SDK ABAP pour Google Cloud permet l'intégration avec les API REST publiées par Google.

Google API Explorer est un outil qui vous permet d'essayer les méthodes API Google Cloud, sans écrire de code. Vous pouvez utiliser cet outil pour examiner les API et les paramètres d'entrée requis que vous souhaitez transmettre à leurs méthodes ABAP correspondantes.

Constructions de code

Décrit les constructions de code qui vous permettent de créer vos programmes ABAP à l'aide du SDK ABAP pour Google Cloud.

Constructeur

Vous devez d'abord instancier la classe d'API que vous souhaitez utiliser. Le constructeur de chaque classe d'API aurait un modèle similaire, comme indiqué dans l'exemple suivant :

    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

Paramètres d'importation

Le tableau suivant décrit les paramètres d'importation d'un constructeur de méthode :

Nom du paramètre Type Obligatoire/Facultatif Description
iv_key_name /GOOG/KEYNAME Obligatoire Spécifiez la clé client de la configuration que vous utilisez pour établir une connexion à Google Cloud. Pour en savoir plus sur la configuration des clés client, consultez la page Authentification.
iv_log_object balobj_d Facultatif Spécifiez l'objet journal de l'application dont vous vous servez pour stocker les erreurs générées par le SDK. Pour obtenir des informations sur la configuration de la journalisation, consultez la section Journalisation des applications.
iv_log_subobject balsubobj Facultatif Spécifiez le sous-objet de journal d'application utilisé pour stocker les erreurs générées par le SDK. Pour obtenir des informations sur la configuration de la journalisation, consultez la section Journalisation des applications.

Méthode API

Dans la conception des API Google Cloud orientée ressource, une méthode API est une action pouvant être effectuée sur une ressource publiée par l'API.

Par exemple, si Topics est une ressource publiée par l'API Pub/Sub, topics.get est une méthode API représentant une action sur la ressource Topics permettant d'obtenir la configuration d'un sujet.

Pour mapper une méthode de classe ABAP à une méthode API, vous pouvez consulter la description de la méthode au format : <resource>.<method_verb>.

Par exemple, la description d'une méthode Pub/Sub est pubsub.projects.topics.get.

  • projects.topics : nom de la ressource.
  • get : action de la méthode.

UI SAP pour la description de la méthode

Le nom d'un mappage de méthode ABAP à une action d'API est au format : <method_verb>_<resource>.

Par exemple, le nom d'une méthode ABAP pour Pub/Sub est GET_TOPICS.

  • GET : action de la méthode.
  • TOPICS : nom de la ressource.

Une méthode ABAP comprend les sections suivantes qui correspondent aux méthodes de l'API REST :

Nom de la méthode

Paramètres d'importation

Une méthode API peut inclure les paramètres d'importation suivants. Ces paramètres sont facultatifs. Vous pouvez les transmettre en fonction des exigences d'une méthode API que vous devez utiliser.

Nom du paramètre Type Catégorie Description

iv_q_NAME

(0 à n)

 Chaîne Paramètres de requête

Les paramètres de requête sont ajoutés au point de terminaison de l'API après (?).

Ils permettent de définir le tri, la pagination ou le filtrage.

Il peut y avoir de 0 à n paramètres de requête.

iv_p_NAME

(0 à n)

 Chaîne Paramètres de chemin d'accès

Les paramètres de chemin d'accès font partie du point de terminaison.

Ils sont utilisés pour pointer vers des ressources d'API REST spécifiques.

Il peut y avoir de 0 à n paramètres de chemin d'accès.

is_input

(0 à 1)

TY_CODE (type de classe)

 Paramètres de la structure d'entrée

Les données transmises en tant que corps de la requête peuvent être mappées à l'aide de la structure d'entrée.

L'API REST accepte la charge utile JSON en tant que corps de requête. Il s'agit d'un paramètre entièrement typé qui est converti en charge utile JSON pour la classe d'API. Le développeur n'est pas tenu d'utiliser JSON.

Vous pouvez consulter les types de classes disponibles pour comprendre les types ABAP nécessaires au mappage des données. Par exemple, le type /GOOG/CL_PUBSUB_V1=>TY_041 est mappé à la ressource REST Topic, qui est transmise en tant que charge utile JSON à la méthode CREATE_TOPICS.

Une méthode ne peut comporter qu'un seul paramètre de corps de requête. Certaines méthodes ne comportent pas de corps de requête.

Paramètres d'exportation

Une méthode API accepte les paramètres d'exportation suivants :

Nom du paramètre Type Catégorie Description
es_raw données Sortie brute

Ce paramètre contient la réponse JSON (erreur ou réussite) renvoyée par la méthode API. Mappez ce paramètre à une variable de type chaîne pour recevoir la chaîne de réponse JSON.

Si la réponse est d'un autre type (par exemple, xstring) pour le résultat du fichier dans /goog/cl_storage_v1->get_objects( ), le paramètre renvoie une valeur appropriée.

Utilisez ce paramètre pour les scénarios de dépannage ou d'API avancés.
es_output TY_CODE (type de classe) Structure de sortie

La réponse JSON est désérialisée dans la structure ABAP et renvoyée à l'aide de ce paramètre d'exportation typé.

Vous pouvez l'utiliser en tant que moyen principal pour lire les réponses de l'API à l'aide des constructions ABAP.
ev_ret_code I (entier) Code renvoyé

Code renvoyé que vous pouvez utiliser pour vérifier si la méthode API a pu remplir sa fonction.

Pour en savoir plus, consultez la section Codes, erreurs et exceptions renvoyés par l'API.
ev_err_text Chaîne Texte de l'erreur

Si l'appel de méthode a échoué, ce paramètre contient le message d'erreur que vous utilisez pour connaître la raison de l'échec.

Pour en savoir plus, consultez la section Codes, erreurs et exceptions renvoyés par l'API.
ev_err_resp
  • Type d'erreur = CHAR 60
  • Description de l'erreur = STRING
 Réponse d'erreur

Ce paramètre fournit des informations supplémentaires sur l'erreur.

Pour en savoir plus, consultez la section Codes, erreurs et exceptions renvoyés par l'API.

Type de classe

Les API Google Cloud utilisent JSON comme format principal pour l'échange de données. Le SDK ABAP pour Google Cloud fournit des types ABAP qui correspondent au schéma JSON attendu par les API Google Cloud.

Ces types ABAP et les types de tables associés sont disponibles en tant que types de classes dans chaque classe d'API fournie par le SDK.

L'exemple suivant présente le type de classe de l'API Pub/Sub /GOOG/CL_PUBSUB_V1.

Type de classe

La description du type de classe TY_041 sous /GOOG/CL_PUBSUB_V1 est mappée à la ressource REST Topic, qui est transmise en tant que charge utile JSON à la méthode CREATE_TOPICS.

Les commentaires ABAP Doc sont ajoutés à toutes les classes de l'API cliente. Lorsque vous utilisez des outils de développement ABAP pour SAP NetWeaver (ADT) pour le développement, ces commentaires décrivent les types de classes.

Codes, erreurs et exceptions renvoyés par l'API

Si une erreur se produit lorsque la méthode API de la classe ABAP est appelée, le SDK ABAP pour Google Cloud transmet les informations liées à l'erreur au programme appelant à l'aide des paramètres d'exportation du SDK ou en générant des exceptions.

Nom de la réponse renvoyée

Code et erreurs renvoyés par l'API

Les API Google Cloud utilisent un modèle d'erreur qui offre une expérience cohérente dans les différentes API. Lorsqu'une méthode d'API Google Cloud est appelée à partir du SDK, les paramètres suivants contiennent le code et les messages renvoyés par l'API :

Pour vérifier l'état d'un appel d'API, utilisez la méthode IS_SUCCESS. Vous pouvez utiliser la valeur de ev_ret_code pour déterminer si un appel d'API a réussi ou non. En général, lorsque ev_ret_code = 2XX, l'appel de méthode est considéré comme ayant réussi. Pour toutes les autres valeurs, l'appel de méthode est considéré comme ayant échoué.

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

Pour certaines API Google Maps Platform, si vous appelez une API avec des entrées non valides, l'API renvoie un code d'état HTTP positif 2XX avec un message d'erreur et un état d'erreur au lieu d'un code d'état d'erreur HTTP (4XX ou 5XX). Ce message d'erreur et l'état d'erreur dans la réponse de l'API peuvent vous aider à résoudre le problème et à corriger les entrées non valides.

Pour ces API Google Maps Platform, en plus du code de retour ev_ret_code, vérifiez le message d'erreur et l'état d'erreur renvoyés dans la réponse de l'API en appelant la méthode IS_STATUS_OK après l'appel d'API. L'extrait de code suivant montre comment utiliser la méthode IS_STATUS_OK :

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

Le paramètre es_err_resp fournit des informations supplémentaires sur l'erreur. Le tableau suivant explique les champs du paramètre es_err_resp.

Champ Valeur
es_err_resp-error_description Message d'erreur reçu de l'API. Cette valeur est identique au paramètre ev_error_text.
es_err_resp-error Description de l'état HTTP renvoyée par le client HTTP SAP.

Gérer les erreurs renvoyées par les API Google Cloud

Suivez les instructions ci-dessous pour gérer les erreurs renvoyées par les API Google Cloud :

  • Codes d'erreur courants : pour obtenir des informations sur les erreurs courantes renvoyées par les API Google Cloud et leur cause, consultez la section Codes d'erreur.

  • Capturer l'erreur détaillée : pour collecter des informations détaillées sur l'erreur renvoyée avec le SDK ABAP pour Google Cloud, utilisez le paramètre d'exportation es_raw des méthodes de la classe du SDK, et mappez ce paramètre sur une variable de type String Cette variable contient une réponse JSON contenant des messages d'erreur détaillés et les violations spécifiques rencontrées par les API.

  • Afficher l'erreur détaillée : utilisez l'une des méthodes suivantes pour afficher des informations détaillées sur l'erreur renvoyée :

    • Debugger : permet d'afficher le contenu de la variable contenant la réponse JSON dans l'outil de débogage ABAP, pour une analyse plus approfondie.

    • IUG SAP : utilisez la classe ABAP cl_demo_output=>display( lv_response ) pour obtenir une représentation visuelle de l'erreur dans un programme de rapport. Si vous utilisez les méthodes d'API dans un programme de rapport et que l'exécution du programme est en mode de premier plan, utilisez la classe ABAP cl_demo_output=>display_json( lv_response ).

      L'extrait de code suivant montre comment afficher la réponse de l'API en cas d'erreur : 

      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.

  • Documentation spécifique aux API : certaines API Google Cloud fournissent des informations détaillées sur les erreurs et des conseils de dépannage dans leur documentation individuelle. Pour résoudre une erreur liée à une API, consultez la documentation spécifique à cette API, par exemple celle de Pub/Sub, de Document AI ou de Cloud Storage.

Exceptions

Lorsqu'une erreur inattendue se produit lors d'un appel de méthode API (par exemple, configuration du SDK incorrecte ou échec de communication HTTP), le SDK génère une exception de classe de type /GOOG/CX_SDK. Vous devez intercepter cette exception dans votre code et rédiger une logique appropriée de gestion des erreurs.

Gérer une exception

Vous pouvez obtenir le message d'erreur en appelant la méthode get_text de la classe d'exception. Le message d'erreur renvoyé par la classe d'exception est au format suivant :

/GOOG/MSG : Return_Code - Error_Message

La cause de l'erreur et la procédure de résolution dépendent de la valeur de Return_Code.

Valeur de Return_Code Cause de l'erreur Solution
461 Le SDK ABAP pour Google Cloud utilise un code de retour spécial, 461, pour indiquer qu'une étape d'installation et de configuration spécifique n'a pas été effectuée ou a été effectuée de manière incorrecte. Le message d'erreur Error_Message correspondant fournit plus de détails sur l'erreur. Vous devez examiner attentivement les instructions d'installation et de configuration du SDK, et vous assurer de bien les suivre.
Toute autre valeur Ce code renvoyé est la dernière erreur HTTP de la classe du client HTTP SAP standard. Cette erreur signifie que le gestionnaire de communication Internet SAP a rencontré un problème de communication lors de l'appel d'une méthode d'API REST Google. Vous devez examiner attentivement votre réseau, votre pare-feu et les paramètres du gestionnaire de communication Internet SAP, et vous assurer que les configurations autorisent les appels HTTP vers les API Google Cloud.

Pour connaître les messages d'erreur types déclenchés dans le SDK ABAP pour Google Cloud et savoir comment les résoudre, consultez le guide de dépannage.

Journalisation

L'édition SAP BTP du SDK ABAP pour Google Cloud vous permet de consigner les messages d'erreur à l'aide d'un framework de journalisation intégré. L'objet /GOOG/LOG_OBJECT et le sous-objet /GOOG/LOG_SUBOBJECT de journal sont envoyés avec le SDK que vous pouvez utiliser pour créer la configuration de journal par défaut. Pour en savoir plus sur la création de la configuration de journal par défaut, consultez la section Configurer la journalisation.

Vous pouvez afficher les journaux d'application à l'aide de l'application Google SDK : afficher les journaux d'application. Pour en savoir plus, consultez la section Afficher les journaux.

Mappage des types de données

Le tableau suivant fournit la liste complète des valeurs type et format compatibles avec le service de découverte des API Google, ainsi que le type de données ABAP correspondant.

Pour en savoir plus sur les valeurs type et format acceptées par le service de découverte des API Google, consultez la page Récapitulatif des types et des formats.

Valeur du type Valeur du format Type de données ABAP Signification
tous TYPE REF TO DATA La propriété peut être associée à n'importe quel type. Définie par la spécification du schéma JSON.
tableau TABLE TYPE WITH NON UNIQUE KEYS Tableau de valeurs JavaScript. La propriété des éléments indique le schéma des valeurs du tableau. Défini par la spécification du schéma JSON.
booléen ABAP_BOOLEAN Valeur booléenne ("true" ou "false"). Définie par la spécification du schéma JSON.
entier int32 INT4 Entier signé de 32 bits Sa valeur minimale est -2 147 483 648 et sa valeur maximale est 2 147 483 647 (incluse).
entier uint32 INT4 Entier non signé de 32 bits. Sa valeur minimale est 0 et sa valeur maximale est 4 294 967 295 (incluse).
nombre double /GOOG/NUM_DOUBLE (chaîne) Format à virgule flottante IEEE 754 64 bits à double précision.
nombre float /GOOG/NUM_FLOAT (chaîne) Format à virgule flottante IEEE 754 32 bits à double précision.
objet TYPES Objet JavaScript. Défini par la spécification du schéma JSON.
chaîne STRING Chaîne arbitraire. Définie par la spécification du schéma JSON.
chaîne octet STRING Chaîne d'octets complétée et encodée en base64 avec une syntaxe sûre pour les URL et les noms de fichiers (parfois appelée "adapté au Web" ou "base64url"). Définie par la norme RFC 4648.
chaîne date STRING Date RFC 3339 au format AAAA-MM-JJ. Définie dans la spécification du schéma JSON.
chaîne date-time STRING Code temporel au format UTC RFC 3339. Il est au format "aaaa-MM-jjTHH:mm:ss.SSSZ". La partie correspondant aux millisecondes (".SSS") est facultative. Défini dans la spécification du schéma JSON.
chaîne google-datetime STRING Code temporel au format UTC RFC 3339. Il est au format "aaaa-MM-jjTHH:mm:ss.SSSZ". La partie correspondant aux millisecondes (".SSS") est facultative.
chaîne google-duration STRING Une chaîne se termine par le suffixe "s" (indiquant les secondes) et est précédée du nombre de secondes, avec des nanosecondes exprimées sous forme de fractions de secondes. Le point est toujours utilisé comme séparateur décimal, et non une virgule.
chaîne google-fieldmask STRING Chaîne dans laquelle les noms de champs sont séparés par une virgule. Les noms des champs sont
représentés selon les conventions de nommage en "lower camel case".
chaîne int64 STRING Entier signé de 64 bits Sa valeur minimale est -9 223 372 036 854 775 808 et sa valeur maximale est 9 223 372 036 854 775 807 (incluse).
chaîne uint64 STRING Entier non signé de 64 bits. Sa valeur minimale est 0 et sa valeur maximale est (2^64)-1 (incluse).

Sérialisation et désérialisation des requêtes et réponses d'API

Par défaut, l'édition SAP BTP du SDK ABAP pour Google Cloud se charge du marshaling et du démarshaling des requêtes et des réponses d'API. Chaque classe ABAP d'une API Google Cloud comporte des types ABAP intégrés pour former l'entrée et la sortie des méthodes. Pour mettre en œuvre une transformation personnalisée de la requête et de la réponse, vous pouvez utiliser l'emplacement d'amélioration avec les définitions SAP BAdI (Business Add In) fournies avec le SDK.

Mettre en œuvre une transformation personnalisée

Le spot d'amélioration /GOOG/ES_TRANSFORM_JSON, fourni avec le SDK, inclut les définitions BAdI suivantes :

  • /GOOG/BADI_SERIALIZE_JSON : pour mettre en œuvre une logique de sérialisation personnalisée
  • /GOOG/BADI_DESERIALIZE_JSON : pour mettre en œuvre une logique de désérialisation personnalisée

Vous pouvez écrire une logique de transformation spécifique dans les implémentations de ces BAdI. Les interfaces de ces BAdI utilisent IV_METHOD_NAME comme paramètre d'importation. Vous utilisez ce paramètre pour séparer la logique de transformation pour chaque API et méthode d'API à l'aide de blocs IF….ENDIF. Dans votre bloc d'implémentation, définissez le paramètre d'exportation EV_HANDLED sur X.

Pour mettre en œuvre une transformation personnalisée, procédez comme suit :

  1. Pour /GOOG/BADI_SERIALIZE_JSON, créez une implémentation d'amélioration :

    • Pour transformer des requêtes API, créez une implémentation pour la définition BAdI /GOOG/BADI_SERIALIZE_JSON avec une classe d'implémentation.
    • Pour transformer les réponses de l'API, créez une implémentation pour la définition BAdI /GOOG/BADI_DESERIALIZE_JSON avec une classe d'implémentation.

  2. Déterminez l'ID de la méthode d'API pour laquelle vous devez écrire la transformation. L'ID de méthode est la concaténation des éléments suivants :

    • Valeur de la constante d'attribut de classe C_SERVICE_NAME
    • Caractère #
    • Description de la méthode de classe API pour laquelle vous devez mettre en œuvre la transformation

    Par exemple, pour écrire des transformations pour la publication de messages dans un sujet Pub/Sub, l'ID de la méthode serait le suivant : pubsub:v1#pubsub.projects.topics.publish

  3. Dans l'implémentation de la méthode de la définition BAdI :

    1. Pour l'ID de la méthode, écrivez votre transformation personnalisée sous un bloc IF….ENDIF block.

    2. Définissez le paramètre d'exportation EV_HANDLED sur X.

      Si EV_HANDLED n'est pas défini sur X, la logique de marshaling et de démarshaling par défaut du SDK est appliquée.

  4. Marquez l'élément API State de la classe de mise en œuvre sur Use System-Internally (Contract C1). La logique de transformation personnalisée est appelée lors de l'exécution. La logique de sérialisation et de désérialisation par défaut fournie avec le SDK est ignorée.

Espace de noms

L'ensemble du code fourni par Google est placé sous l'espace de noms réservé /GOOG/.

Obtenir de l'aide

Procédez comme suit si vous avez besoin d'aide pour résoudre les problèmes liés au SDK ABAP pour Google Cloud :