Desarrollo de aplicaciones con la edición SAP BTP del SDK de ABAP para Google Cloud

En este documento, se proporciona información y recursos útiles a fin de ayudarte a desarrollar aplicaciones SAP con la edición SAP BTP del SDK de ABAP para Google Cloud.

Este documento está dirigido a desarrolladores de SAP ABAP.

Si deseas obtener una lista completa de las bibliotecas cliente que proporciona la edición SAP BTP del SDK de ABAP para Google Cloud, consulta el SDK de ABAP para las bibliotecas cliente de Google Cloud.

Ventana única de interacción

Cada API de Google Cloud habilitada en el SDK de ABAP para Google Cloud se representa mediante una clase ABAP, incluida en el paquete /GOOG/CLIENT. Una clase ABAP consta de varios métodos públicos, y cada uno de ellos corresponde a un método de la API de Google Cloud. Cada método público consta de los parámetros IMPORTING y los parámetros EXPORTING. Una clase ABAP también contiene tipos de datos personalizados, que se pueden usar para construir y mapear los parámetros IMPORTING y EXPORTING. Estos tipos de datos personalizados se asignan a las definiciones de esquema de la API.

Para cada interacción con una API de Google Cloud de destino, su clase ABAP correspondiente actúa como el único punto de interacción. Este concepto se denomina ventana única de interacción y protege todas las complejidades subyacentes de interactuar con una API de Google Cloud y presenta una interfaz simplificada. Esta interfaz simplificada te permite enfocarte en las soluciones empresariales que se desarrollan mediante el SDK, sin preocuparte por las funciones subyacentes del SDK.

Ventana única de interacción

Flujo de interacción

Para llamar a un método de API, tienes el siguiente flujo de interacción:

  1. Conéctate a una API.
  2. Crea una solicitud de entrada mediante los tipos ABAP.
  3. Llama a un método de API.
  4. Analizar errores y excepciones.
  5. Lee la respuesta mediante los tipos de ABAP.

Interacción con desarrolladores

Stub de cliente de API

Una clase de stub de cliente de API típica consta de las siguientes secciones:

  • Los tipos de ABAP que se asignan a los esquemas de API. Usas tipos ABAP para crear una solicitud de entrada y analizar la respuesta.
  • Las constantes y los atributos para uso interno o externo.
  • Los métodos de API para interactuar con los recursos de API.

Estructura de clases

Funciones

El SDK de ABAP para Google Cloud incluye las siguientes características:

  • Comunicación HTTP: el SDK establece la conexión HTTP con los extremos de la API.
  • Conversión de las solicitudes: El SDK convierte los datos de tipos ABAP a una carga útil de JSON que se envía como el cuerpo de la solicitud.
  • Control de errores y excepciones: el SDK controla los códigos de retorno y los mensajes de error que muestra la API, y genera excepciones, si las hay.
  • Respuesta de desconversión: el SDK revierte la conversión de la carga útil JSON en el cuerpo de la respuesta a los tipos ABAP correspondientes.
  • Registro de errores locales: el SDK registra los mensajes de error con el marco de trabajo de registro.

Diseño de APIs y Explorador de APIs de Google

Las APIs que publica Google siguen un diseño orientado a los recursos. Para obtener más información sobre el diseño de las APIs de Google, consulta la Guía de diseño de APIs.

El SDK de ABAP para Google Cloud habilita la integración con las APIs basadas en REST que publica Google.

El Explorador de APIs de Google es una herramienta que te permite probar métodos de las APIs de Google Cloud sin escribir código. Puedes usar esta herramienta para estudiar las APIs y los parámetros de entrada necesarios que deseas pasar a sus métodos ABAP correspondientes.

Construcciones de código

Explica las construcciones de código que usas para crear tus programas de ABAP con el SDK de ABAP para Google Cloud.

Constructor

Primero, crea una instancia de la clase de API que deseas usar. El constructor de cada clase de API tendría un patrón similar como se muestra en el siguiente ejemplo:

    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

Parámetros de importación

En la siguiente tabla, se explican los parámetros de importación de un constructor de método:

Nombre del parámetro Tipo Obligatorio/opcional Descripción
iv_key_name /GOOG/KEYNAME Obligatorio Especifica la clave de cliente de la configuración que usas para crear una conexión con Google Cloud. Para obtener más información sobre la configuración de las claves de cliente, consulta Autenticación.
iv_log_object balobj_d Opcional Especifica el objeto de registro de la aplicación, que se usa para almacenar los errores generados por el SDK. Para obtener información sobre la configuración del registro, consulta Registro de aplicaciones.
iv_log_subobject balsubobj Opcional Especifica el subobjeto de registro de la aplicación, que se usa para almacenar los errores generados por el SDK. Para obtener información sobre la configuración del registro, consulta Registro de aplicaciones.

Método de la API

Con el diseño orientado a los recursos de las APIs de Google Cloud, un método de API es una acción que se puede ejecutar en un recurso publicado por la API.

Por ejemplo, si Topics es un recurso publicado por la API de Pub/Sub, topics.get es un método de API que representa una acción en el recurso Topics para obtener la configuración de un tema.

Para asignar un método de clase ABAP a un método de API, puedes consultar la descripción del método que sigue el patrón <resource>.<method_verb>.

Por ejemplo, la descripción del método para un método de Pub/Sub es pubsub.projects.topics.get.

  • projects.topics: Es el nombre del recurso.
  • get: es la acción del método.

IU de SAP de descripción del método

El nombre en un método ABAP que se asigna a una acción de la API sigue el patrón <method_verb>_<resource>.

Por ejemplo, el nombre del método ABAP para Pub/Sub es el siguiente: GET_TOPICS

  • GET: es la acción del método.
  • TOPICS: Es el nombre del recurso.

Un método ABAP consta de las siguientes secciones que se asignan a los métodos de la API de REST:

Nombre del método

Parámetros de importación

Un método de API puede tener los siguientes parámetros de importación. Estos parámetros son opcionales y puedes pasar los parámetros según los requisitos de un método de API que necesites usar.

Nombre del parámetro Tipo Categoría Descripción

iv_q_NAME

(0 a n)

 String Parámetros de consulta

Los parámetros de consulta se agregan al extremo de la API después (?).

Se usan para definir el orden, la paginación o el filtro.

Puede haber parámetros de consulta 0 a n.

iv_p_NAME

(0 a n)

 String Parámetros de ruta

Los parámetros de ruta son parte del extremo.

Se usan para apuntar a recursos específicos de la API de REST.

Podría haber parámetros de ruta de 0 a n.

is_input

(0 a 1)

TY_CODE (Tipo de clase)

 Parámetros de estructura de entrada

Los datos que se pasan como el cuerpo de la solicitud se pueden asignar con la estructura de entrada.

La API de REST acepta la carga útil de JSON como el cuerpo de la solicitud. El parámetro es un parámetro con tipo completo que se convierte en una carga útil de JSON para la clase de API, y no es necesario que el desarrollador trabaje con JSON.

Puedes consultar los tipos de clases disponibles para comprender los tipos de ABAP a fin de asignar los datos. Por ejemplo, el tipo /GOOG/CL_PUBSUB_V1=>TY_041 se asigna al recurso REST Topic, que se pasa como la carga útil JSON al método CREATE_TOPICS.

Un método puede tener un máximo de un parámetro de cuerpo de solicitud. Algunos métodos no tienen un cuerpo de la solicitud.

Exporta parámetros

Un método de API admite los siguientes parámetros de exportación:

Nombre del parámetro Tipo Categoría Descripción
es_raw datos Resultado sin procesar

Este parámetro contiene la respuesta JSON (Error o Success) que muestra el método de la API. Asigna este parámetro a una variable de tipo String para recibir la cadena de la respuesta JSON.

En los casos en que la respuesta sea de cualquier otro tipo, por ejemplo, xstring para el resultado del archivo en /goog/cl_storage_v1->get_objects( ), el parámetro muestra un valor apropiado.

Usa este parámetro para situaciones avanzadas de solución de problemas o situaciones de API avanzadas.
es_output TY_CODE (Tipo de clase) Estructura de salida

La respuesta JSON se deserializa a la estructura ABAP y se muestra con este parámetro de exportación con tipo.

Puedes usar esto como la forma principal de leer las respuestas de la API con construcciones de ABAP.
ev_ret_code I (Entero) Código de retorno

El código de retorno que puedes usar para verificar si la ejecución del método de la API pudo realizar su funcionalidad de forma correcta.

Para obtener más información, consulta Códigos de retorno de la API, errores y excepciones.
ev_err_text String Texto de error

Si la llamada de método falló, este parámetro contiene el mensaje de error que usas para conocer el motivo de la falla.

Para obtener más información, consulta Códigos de retorno, errores y excepciones de la API.
ev_err_resp
  • Tipo de error = CHAR 60
  • Descripción del error = STRING
 Respuesta de error

El parámetro proporciona información adicional sobre el error.

Para obtener más información, consulta Códigos de retorno de la API, errores y excepciones.

Tipo de clase

Las APIs de Google Cloud usan JSON como el formato principal para el intercambio de datos. El SDK de ABAP para Google Cloud proporciona tipos ABAP que se asignan al esquema JSON que esperan las APIs de Google Cloud.

Estos tipos de ABAP y los tipos de tablas relacionados están disponibles como tipos de clase en cada clase de API que proporciona el SDK.

En el siguiente ejemplo, se muestra el tipo de clase para la clase de API de Pub/Sub /GOOG/CL_PUBSUB_V1.

Tipo de clase

La descripción del tipo de clase TY_041 en /GOOG/CL_PUBSUB_V1 se asigna al recurso REST, Topic, que se pasa como carga útil JSON al método CREATE_TOPICS.

Los comentarios ABAP Doc se agregan a todas las clases de API del cliente. Cuando usas las herramientas de desarrollo de ABAP para SAP NetWeaver (ADT) para el desarrollo, estos comentarios te proporcionan descripciones de los tipos de clase.

Códigos de retorno, errores y excepciones de la API

Si se produce un error cuando se llama al método de API de la clase ABAP, el SDK de ABAP pasa la información del error al programa que realiza la llamada mediante el exportación de parámetros del SDK o la generación de excepciones.

Nombre de la respuesta de retorno

Código de retorno y errores de la API

Las APIs de Google Cloud usan un modelo de error que ofrece una experiencia coherente en las diferentes APIs. Cuando se llama al método de la API de Google Cloud desde el SDK, los siguientes parámetros contienen el código y los mensajes de retorno de la API:

Para verificar el estado de una llamada a la API, usa el método IS_SUCCESS. Puedes usar el valor de ev_ret_code para determinar si una llamada de la API se realizó de forma correcta o no. En general, cuando se usa ev_ret_code = 2XX, la llamada de método se considera correcta. Para todos los demás valores, la llamada de método se considera incorrecta.

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

Para algunas API de Google Maps Platform, en caso de que llames a una API con entradas no válidas, la API muestra un código de estado de éxito HTTP 2XX con un mensaje de error y un estado de error en lugar de un código de estado de error HTTP (4XX o 5XX). Este mensaje de error y este estado de error en la respuesta de la API pueden ayudarte a solucionar el problema y a corregir las entradas no válidas.

Para esas APIs de Google Maps Platform, además del código de retorno ev_ret_code, verifica el mensaje y el estado del error que se muestran en la respuesta de la API a través de una llamada al método IS_STATUS_OK después de la llamada a la API. En el siguiente fragmento, se muestra un ejemplo de cómo puedes usar el método IS_STATUS_OK:

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

El parámetro es_err_resp proporciona información adicional sobre el error. En la siguiente tabla, se explican los campos del parámetro es_err_resp.

Campo Valor
es_err_resp-error_description Mensaje de error recibido de la API. Este valor es igual que el parámetro ev_error_text.
es_err_resp-error Descripción de estado HTTP que muestra el cliente HTTP de SAP.

Maneja los errores que muestran las APIs de Google Cloud

Usa la siguiente guía para controlar los errores que muestran las APIs de Google Cloud:

  • Códigos de error comunes: Para obtener información sobre los errores comunes que muestran las APIs de Google Cloud y sus causas, consulta Códigos de error.

  • Captura información detallada sobre los errores: a fin de capturar información de errores detallada con el SDK de ABAP para Google Cloud, usa el parámetro de exportación es_raw de los métodos de clase del SDK y asigna este parámetro a una variable de tipo String Esta variable tiene una respuesta JSON que contiene mensajes de error detallados y las infracciones específicas que encuentran las APIs.

  • Visualiza un error en detalle: Para ver la información de errores detallada, usa uno de los siguientes métodos:

    • Debugger: Consulta el contenido de la variable que contiene la respuesta JSON dentro de la herramienta de depuración de ABAP para un análisis más detallado.

    • GUI de SAP: usa la clase cl_demo_output=>display( lv_response ) de ABAP para la representación visual del error dentro de un programa de informes. Si usas los métodos de la API en un programa de informes y la ejecución del programa está en modo de primer plano, usa la clase de ABAP cl_demo_output=>display_json( lv_response ).

      En el siguiente fragmento de código, se muestra cómo mostrar la respuesta de la API en caso de un error: 

      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.

  • Documentación específica de la API: Algunas APIs de Google Cloud proporcionan información detallada sobre los errores y orientación para solucionar problemas dentro de la documentación individual. Para resolver un error relacionado con una API, consulta la documentación específica de esa API, por ejemplo, Pub/Sub, Document AI y Cloud Storage.

Excepciones

Cuando se produce un error inesperado durante una llamada de método de la API, como una configuración incorrecta del SDK o una falla de la comunicación HTTP, el SDK genera una excepción de clase del tipo /GOOG/CX_SDK. Debes detectar esta excepción en tu código y escribir una lógica de manejo de errores adecuada.

Controla la excepción

Para obtener el mensaje de error, llama al método get_text de la clase de excepción. El mensaje de error que muestra la clase de excepción tiene el siguiente formato:

/GOOG/MSG : Return_Code - Error_Message

La causa de los pasos de error y resolución depende del valor de Return_Code.

Valor de Return_Code Causa del error Solución
461 El SDK de ABAP para Google Cloud usa un código de retorno especial, 461, a fin de informar que un paso de instalación y configuración específico no se completó o se completó de forma incorrecta. El Error_Message correspondiente proporciona más detalles sobre el error. Debes revisar con cuidado las instrucciones de instalación y configuración del SDK y asegurarte de que estén realizadas de forma correcta.
Cualquier otro valor Este código de retorno es el último error de HTTP de la clase estándar del cliente HTTP de SAP. Este error significa que SAP ICM tuvo un problema de comunicación cuando se llamó a un método de la API de REST de Google. Debes revisar con cuidado tu red, firewall, configuración de ICM de SAP y asegurarte de que la configuración permita llamadas HTTP a las APIs de Google Cloud.

Para ver los mensajes de error típicos que se activan en el SDK de ABAP para Google Cloud y su resolución, consulta la guía de solución de problemas.

Logging

La edición SAP BTP del SDK de ABAP para Google Cloud te permite registrar mensajes de error mediante un framework de registro incorporado. El objeto de registro /GOOG/LOG_OBJECT y el subobjeto /GOOG/LOG_SUBOBJECT se envían con el SDK que puedes usar para crear tu configuración de registro predeterminada. Para obtener más información sobre cómo crear una configuración de registro predeterminada, consulta Configura el registro.

Puedes ver los registros de la aplicación con la app SDK de Google: visualización de los registros de la aplicación. Para obtener más información, consulta Visualiza registros.

Asignación de tipos de datos

En la siguiente tabla, se proporciona una lista completa de los valores type y format compatibles con Discovery Service de las APIs de Google y el tipo de datos ABAP correspondiente.

Para obtener más información sobre los valores type y format compatibles con Discovery Service de las APIs de Google, consulta Resumen de tipo y formato.

Valor del tipo Valor del formato Tipo de datos ABAP Significado
cualquiera TYPE REF TO DATA La propiedad puede tener cualquier tipo. Definido por la especificación del esquema de JSON.
array TABLE TYPE WITH NON UNIQUE KEYS Un array de valores de JavaScript. La propiedad del elemento indica el esquema de los valores del array. Definido por la especificación del esquema de JSON.
booleano ABAP_BOOLEAN Un valor booleano, ya sea "true" o "false". Definido por la especificación del esquema de JSON.
número entero int32 INT4 Un número entero de 32 bits con firma. Tiene un valor mínimo de -2,147,483,648 y un valor máximo de 2,147,483,647 (inclusive).
número entero uint32 INT4 Un número entero de 32 bits sin firma. Tiene un valor mínimo de 0 y un valor máximo de 4,294,967,295 (inclusive).
número double /GOOG/NUM_DOUBLE (string) Un punto flotante IEEE 754 de 64 bits de doble precisión
número float /GOOG/NUM_FLOAT (string) Un punto flotante IEEE 754 de 32 bits de precisión única.
objeto TYPES Un objeto JavaScript. Definido por la especificación del esquema de JSON.
string STRING Una cadena arbitraria. Definido por la especificación del esquema de JSON.
string byte STRING Una cadena de bytes codificada en Base64, codificada con una URL y un alfabeto seguro para el nombre de archivo (a veces denominado “web-safe” o “base64url”). Definido por RFC 4648.
string fecha STRING Una fecha RFC 3339 en el formato AAAA-MM-DD. Se define en la especificación del esquema de JSON.
string date-time STRING Una marca de tiempo RFC 3339 en hora UTC. Tiene el formato aaaa-MM-ddTHH:mm:ss.SSSZ. La parte de milisegundos (“.SSS”) es opcional. Se define en la especificación del esquema de JSON.
string google-datetime STRING Una marca de tiempo RFC 3339 en hora UTC. Tiene el formato aaaa-MM-ddTHH:mm:ss.SSSZ. La parte de milisegundos (“.SSS”) es opcional.
string google-duration STRING Una string termina en el sufijo “s” (indica los segundos) y está precedida por la cantidad de segundos, con nanosegundos expresados como segundos fraccionarios. El punto siempre se usa como separador de decimales, en lugar de una coma.
string google-fieldmask STRING Una string en la que los nombres de campos están separados por comas. Los nombres de los campos se
representan con convenciones de nomenclatura de mayúsculas mediales con minúscula inicial.
string int64 STRING Un número entero de 64 bits con firma. Tiene un valor mínimo de -9,223,372,036,854,775,808 y un valor máximo de 9,223,372,036,854,775,807 (inclusive).
string uint64 STRING Un número entero de 64 bits sin firma. Tiene un valor mínimo de 0 y un valor máximo de (2^64)-1 (inclusive).

Serialización y deserialización de la solicitud y respuesta a la API

De forma predeterminada, la edición SAP BTP del SDK de ABAP para Google Cloud se encarga de serializar y deserializar las solicitudes y respuestas a la API. Cada clase ABAP para una API de Google Cloud tiene tipos ABAP incorporados para formar la entrada y salida de los métodos. Para implementar la transformación personalizada de solicitud y respuesta, puedes usar el espacio de mejora con las definiciones de complemento empresarial (BAdI) de SAP que se envían con el SDK.

Implementa una transformación personalizada

El espacio de mejora /GOOG/ES_TRANSFORM_JSON, que se envía con el SDK, incluye las siguientes definiciones de BAdI:

  • /GOOG/BADI_SERIALIZE_JSON: para implementar la lógica de serialización personalizada.
  • /GOOG/BADI_DESERIALIZE_JSON: para implementar la lógica de deserialización personalizada.

Puedes escribir una lógica de transformación específica en las implementaciones de estos BAdI. Las interfaces de estos BAdI tienen IV_METHOD_NAME como parámetro de importación. Usa este parámetro a fin de segregar la lógica de transformación para cada API y método de la API a través de bloques IF….ENDIF. En el bloque de implementación, configura el parámetro de exportación EV_HANDLED como X.

Para implementar una transformación personalizada, sigue estos pasos:

  1. Para /GOOG/BADI_SERIALIZE_JSON, crea una implementación de mejora:

    • Para transformar las solicitudes a la API, crea una implementación para /GOOG/BADI_SERIALIZE_JSON de BAdI con una clase de implementación.
    • Para transformar las respuestas de la API, crea una implementación para /GOOG/BADI_DESERIALIZE_JSON de BAdI con una clase de implementación.

  2. Determina el ID de método del método de la API en el que necesitas escribir la transformación. El ID de método es la concatenación de lo siguiente:

    • El valor de la constante de atributo de clase C_SERVICE_NAME.
    • El carácter #.
    • La descripción del método de clase de la API para el que necesitas implementar la transformación.

    Por ejemplo, para escribir transformaciones para publicar mensajes en un tema de Pub/Sub, el ID de método sería pubsub:v1#pubsub.projects.topics.publish.

  3. En la implementación del método de BAdI:

    1. Para el ID de método, escribe tu transformación personalizada en un IF….ENDIF block.

    2. Configura el parámetro de exportación EV_HANDLED como X.

      Si EV_HANDLED no está configurado como X, se aplica la lógica para asociar y desasociar predeterminada del SDK.

  4. Marca el API State de la clase de implementación como Use System-Internally (Contract C1). La lógica de transformación personalizada se invoca durante el tiempo de ejecución. Se omitirá la lógica predeterminada de serialización y deserialización enviada con el SDK.

Espacio de nombres

Todo el código proporcionado por Google se coloca bajo el espacio de nombres reservado /GOOG/.

Obtenga asistencia

Si necesitas ayuda para resolver problemas con el SDK de ABAP para Google Cloud, haz lo siguiente: