This document provides you with useful information and resources to help you develop SAP applications using the SAP BTP edition of ABAP SDK for Google Cloud.
This document is intended for SAP ABAP developers.
For a complete list of client libraries that the SAP BTP edition of ABAP SDK for Google Cloud provides, see ABAP SDK for Google Cloud client libraries.
Single-window of interaction
Each Google Cloud API enabled in the ABAP SDK for Google Cloud is represented
by an ABAP class, contained in the package /GOOG/CLIENT
. An ABAP class consists
of multiple public methods and each of these public methods corresponds to a
Google Cloud API method. Each public method further consists of
IMPORTING
parameters and EXPORTING
parameters. An ABAP class also contains
custom data types, which can be used to construct and map the IMPORTING
and EXPORTING
parameters. These custom data types map to the API schema
definitions.
For every interaction with a target Google Cloud API, its corresponding ABAP class acts as the only interaction point. We call this concept, Single-window of interaction, which shields all the underlying complexities of interacting with a Google Cloud API and presents a simplified interface. This simplified interface lets you focus on the business solutions being developed using the SDK, without worrying about the underlying SDK features.
Interaction flow
To call an API method, you have the following interaction flow:
- Connect to an API.
- Construct an input request using the ABAP types.
- Call an API method.
- Parse errors and exceptions.
- Read the response using the ABAP types.
API client stub
A typical API client stub class consist of the following sections:
- The ABAP types that map to the API schemas. You use ABAP types to construct an input request and parse the response.
- The constants and attributes for internal or external usage.
- The API methods for interacting with API resources.
Features
The ABAP SDK for Google Cloud includes the following features:
- HTTP communication: the SDK establishes HTTP connection with the API endpoints.
- Request marshaling: the SDK converts data in ABAP types to JSON payload that is sent as the request body.
- Error and exception handling: the SDK handles the return codes and error messages returned by the API, and raises exceptions, if any.
- Unmarshalling response: the SDK converts back the JSON payload in the response body to corresponding ABAP types.
- Local error logging: the SDK logs error messages using the logging framework.
API design and Google API Explorer
APIs published by Google follow resource-oriented design. To learn more about Google's API design, see the API design guide.
The ABAP SDK for Google Cloud enables integration with the REST based APIs published by Google.
Google API Explorer is a tool that lets you try Google Cloud API methods without writing code. You can use this tool to study the APIs and required input parameters that you want to pass to their corresponding ABAP methods.
Code constructs
Explains the code constructs that you use to create your ABAP programs using the ABAP SDK for Google Cloud.
Constructor
You first instantiate the API class that you want to use. The constructor of every API class would have a similar pattern as shown in the following example:
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
Importing parameters
The following table explains the importing parameters of a method constructor:
Parameter name | Type | Required/Optional | Description |
---|---|---|---|
iv_key_name |
/GOOG/KEYNAME |
Required | Specify the client key from the configuration that you use to create a connection to Google Cloud. For information about client key configuration, see Authentication. |
iv_log_object |
balobj_d |
Optional | Specify the application log object, which you use to store the SDK generated errors. For information about logging configuration, see Application logging. |
iv_log_subobject |
balsubobj |
Optional | Specify the application log subobject, which you use to store the SDK generated errors. For information about logging configuration, see Application logging. |
API method
With resource-oriented design of Google Cloud APIs, an API method is an action that can be performed on a resource published by the API.
For example, if Topics
is a resource published by Pub/Sub API, then
topics.get
is an API method that represent an action on
the resource Topics
to get the configuration of a topic.
To map an ABAP class method to an API method,
you can refer to the method description that follows the
pattern:<resource>.<method_verb>
.
For example, the method description for a Pub/Sub method is
pubsub.projects.topics.get
.
projects.topics
: the resource name.get
: the method action.
The name on an ABAP method mapping to an API action follows the pattern:<method_verb>_<resource>
.
For example, an ABAP method name for Pub/Sub is: GET_TOPICS
GET
: the method action.TOPICS
: the resource name.
An ABAP method consists of the following sections that map to the REST API methods:
Importing parameters
An API method can have the following importing parameters. These parameters are optional and you can pass the parameters based on the requirements of an API method that you need to use.
Parameter name | Type | Category | Description |
---|---|---|---|
( |
String | Query parameters | The query parameters are appended to the API endpoint after ( They are used to define sort, pagination, or filter. There could be |
( |
String | Path parameters | The path parameters are part of the endpoint. They are used to point to specific REST API resources. There could be |
( |
TY_CODE (Class type) |
Input structure parameters | The data passed as the request body can be mapped using input structure. The REST API accepts JSON payload as request body. The parameter is a fully-typed parameter that is converted into JSON payload for the API class and the developer is not required to work with JSON. You can refer to the available class types to understand
the ABAP types for mapping the data. For example,
Type A method can have a maximum of one request body parameter. Some methods don't have a request body. |
Exporting parameters
An API method supports the following exporting parameters:
Parameter name | Type | Category | Description |
---|---|---|---|
es_raw |
data | Raw output |
This parameter holds the JSON response (Error or Success) returned by the API method. Map this parameter to a variable of type String to receive the JSON response string. In cases where the response is of any other type, for example,
xstring for file output in Use this parameter for advanced troubleshooting scenarios or for advanced API scenarios. |
es_output |
TY_CODE (Class Type) | Output structure |
The JSON response is deserialized to ABAP structure and returned using this typed exporting parameter. You can use this as the primary way to read the API responses using ABAP constructs. |
ev_ret_code |
I (Integer) | Return code |
The return code that you can use to verify if the API method execution was able to successfully perform its functionality. For more information, see API return codes, errors, and exceptions. |
ev_err_text |
String | Error text |
If the method call failed, then this parameter contains the error message that you use to know the reason of failure. For more information, see API return codes, errors, and exceptions. |
ev_err_resp |
|
Error response |
The parameter provides additional information about the error. For more information, see API return codes, errors, and exceptions. |
Class type
Google Cloud APIs use JSON as the primary format for data exchange. The ABAP SDK for Google Cloud provides ABAP types that map to the JSON schema expected by the Google Cloud APIs.
These ABAP types and related table types are available as class types in every API class that the SDK provides.
The following example shows class type for Pub/Sub API class /GOOG/CL_PUBSUB_V1
.
The description of class type TY_041
under /GOOG/CL_PUBSUB_V1
maps to the REST Resource, Topic
, which is passed as JSON Payload
to the method CREATE_TOPICS
.
ABAP Doc
comments are added to all client API classes.
While using ABAP Development Tools for SAP NetWeaver (ADT) for development,
these comments provide you descriptions of the class types.
API return codes, errors, and exceptions
If an error occurs when the API method of ABAP class is called, the ABAP SDK for Google Cloud passes the error information to the calling program by using the SDK exporting parameters or by raising exceptions.
API return code and errors
Google Cloud APIs use an error model that offers consistent experience across different APIs. When a Google Cloud API method is called from the SDK, the following parameters contain the API return code and messages:
ev_ret_code
: return code or error code in the response.ev_error_text
: error message in the response, if any.es_raw
: raw error response, if an API method call failed.
To check the status of an API call, use the IS_SUCCESS
method. You can use the
value of ev_ret_code
to determine if an API call was
successful or not. In general, when ev_ret_code = 2XX
, the method call is
considered to be successful. For all other values, the method call is considered
unsuccessful.
IF lo_client->is_success( ev_ret_code ).
"Success: Implement custom code
ELSE
"Handle the HTTP error status code
ENDIF.
For some Google Maps Platform APIs, in case you call an API with
invalid inputs, the API returns an HTTP success status code 2XX
with
an error message and error status, instead of an HTTP error status code
(4XX
or 5XX
). This error message and error status in the API
response can help you troubleshoot the problem and fix the invalid inputs.
For such Google Maps Platform APIs, in addition to the
return code ev_ret_code
, check the error message and error status
returned in the API response by calling the IS_STATUS_OK
method after
the API call. The following snippet shows an example of how you can
use the IS_STATUS_OK
method:
IF lo_client->is_status_ok( ).
"Success: Implement custom code
ELSE
"Handle the HTTP error status code
ENDIF.
The parameter es_err_resp
provides additional information about the error.
The following table explains the fields in the parameter es_err_resp
.
Field | Value |
---|---|
es_err_resp-error_description |
Error message received from the API. This value is same as the parameter ev_error_text . |
es_err_resp-error |
HTTP status description returned from the SAP HTTP client. |
Handle errors returned by Google Cloud APIs
Use the following guidance to handle errors returned by Google Cloud APIs:
Common error codes: For information about common errors returned by Google Cloud APIs and their cause, see error codes.
Capture detailed error: To capture detailed error information with ABAP SDK for Google Cloud, use the exporting parameter
es_raw
from the SDK class methods and map this parameter to a variable of typeString
. This variable holds a JSON response containing detailed error messages and specific violations encountered by the APIs.View detailed error: To view detailed error information, use one of the following methods:
- Debugger: View the contents of the variable that holds the JSON response within the ABAP debugger tool for further analysis.
SAP GUI: Use the ABAP class
cl_demo_output=>display( lv_response )
for visual representation of the error within a report program. If you are using the API methods in a report program and the program execution is in foreground mode, then use the ABAP classcl_demo_output=>display_json( lv_response )
.The following code snippet illustrates how to display API response in case of an 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.
API specific documentation: Some Google Cloud APIs provide detailed error information and troubleshooting guidance within their individual documentation. To resolve an error related to an API, see the documentation specific to that API, for example, Pub/Sub, Document AI, and Cloud Storage.
Exceptions
When an unexpected error occurs during an API method call, such as incorrect SDK
configuration or HTTP communication failure, the SDK raises
a class exception of type /GOOG/CX_SDK
. You must catch this exception in your
code and write an appropriate error handling logic.
You can get the error message by calling the method get_text
of the exception
class. The error message returned by the exception class has the following format:
/GOOG/MSG : Return_Code - Error_Message
The cause of the error and resolution steps depends on the value of Return_Code
.
Value of Return_Code |
Cause of the error | Resolution |
---|---|---|
461 |
The ABAP SDK for Google Cloud uses a special return code, 461 , to
inform that a specific installation and configuration step is not done
or completed incorrectly. Corresponding Error_Message provides
more details about the error. |
You must carefully review the installation and configuration instructions for the SDK and ensure they are done correctly. |
Any other value | This return code is the last HTTP error from the standard SAP HTTP Client Class. This error signifies that the SAP ICM faced a communication issue when calling a Google REST API method. | You must carefully review your network, firewall, SAP ICM settings, and make sure that configurations allow HTTP calls to Google Cloud APIs. |
For typical error messages triggered in the ABAP SDK for Google Cloud and their resolution, see the troubleshooting guide.
Logging
The SAP BTP edition of ABAP SDK for Google Cloud lets you log error messages
using an embedded logging framework. The log object /GOOG/LOG_OBJECT
and subobject
/GOOG/LOG_SUBOBJECT
are shipped with the SDK that you can use for
creating your default log configuration. For more information about creating
default log configuration, see Configure logging.
You can view application logs using the Google SDK:Application Logs Display app. For more information, see View logs.
Data type mapping
The following table provides a full list of type
and format
values supported by Google APIs Discovery Service and corresponding
ABAP data type.
For more information about type
and format
values supported by Google APIs Discovery Service, see Type and format summary.
Type value | Format value | ABAP data type | Meaning |
---|---|---|---|
any | TYPE REF TO DATA | The property may have any type. Defined by the JSON Schema spec. | |
array | TABLE TYPE WITH NON UNIQUE KEYS | A JavaScript array of values. The items property indicates the schema for the array values. Defined by the JSON Schema spec. | |
boolean | ABAP_BOOLEAN | A boolean value, either "true" or "false". Defined by the JSON Schema spec. | |
integer | int32 | INT4 | A 32-bit signed integer. It has a minimum value of -2,147,483,648 and a maximum value of 2,147,483,647 (inclusive). |
integer | uint32 | INT4 | A 32-bit unsigned integer. It has a minimum value of 0 and a maximum value of 4,294,967,295 (inclusive). |
number | double | /GOOG/NUM_DOUBLE (string) |
A double-precision 64-bit IEEE 754 floating point. |
number | float | /GOOG/NUM_FLOAT (string) |
A single-precision 32-bit IEEE 754 floating point. |
object | TYPES | A JavaScript object. Defined by the JSON Schema spec. | |
string | STRING | An arbitrary string. Defined by the JSON Schema spec. | |
string | byte | STRING | A padded, base64-encoded string of bytes, encoded with a URL and filename safe alphabet (sometimes referred to as "web-safe" or "base64url"). Defined by RFC 4648. |
string | date | STRING | An RFC 3339 date in the format YYYY-MM-DD. Defined in the JSON Schema spec. |
string | date-time | STRING | An RFC 3339 timestamp in UTC time. This in the format of yyyy-MM-ddTHH:mm:ss.SSSZ. The milliseconds portion (".SSS") is optional. Defined in the JSON Schema spec. |
string | google-datetime | STRING | An RFC 3339 timestamp in UTC time. This in the format of yyyy-MM-ddTHH:mm:ss.SSSZ. The milliseconds portion (".SSS") is optional. |
string | google-duration | STRING | A string ends in the suffix "s" (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. The period is always used as the decimal point, not a comma. |
string | google-fieldmask | STRING | A string where field names are separated by a comma. Field names are represented in lower-camel naming conventions. |
string | int64 | STRING | A 64-bit signed integer. It has a minimum value of -9,223,372,036,854,775,808 and a maximum value of 9,223,372,036,854,775,807 (inclusive). |
string | uint64 | STRING | A 64-bit unsigned integer. It has a minimum value of 0 and a maximum value of (2^64)-1 (inclusive). |
Serialization and deserialization of API request and response
By default, the SAP BTP edition of ABAP SDK for Google Cloud takes care of marshalling and unmarshalling API requests and responses. Each ABAP class for a Google Cloud API has embedded ABAP types to form the input and output of the methods. To implement custom transformation of request and response, you can use the enhancement spot with SAP Business Add In (BAdI) definitions that are shipped with the SDK.
Implement custom transformation
The enhancement spot /GOOG/ES_TRANSFORM_JSON
, which is shipped with the SDK,
includes the following BAdI definitions:
/GOOG/BADI_SERIALIZE_JSON
: to implement custom serialization logic./GOOG/BADI_DESERIALIZE_JSON
: to implement custom deserialization logic.
You can write specific transformation logic in implementations of these BAdIs.
The interfaces of these BAdIs have IV_METHOD_NAME
as the importing parameter.
You use this parameter to segregate the transformation logic for each API and
API method using IF….ENDIF
blocks. In your implementation block, set
the exporting parameter EV_HANDLED
to X
.
To implement custom transformation, follow these steps:
For
/GOOG/BADI_SERIALIZE_JSON
, create an enhancement implementation:- For transforming API requests, create an implementation for BAdI
/GOOG/BADI_SERIALIZE_JSON
with an implementation class. - For transforming API responses, create an implementation for BAdI
/GOOG/BADI_DESERIALIZE_JSON
with an implementation class.
- For transforming API requests, create an implementation for BAdI
Determine the method ID of the API method for which you need to write the transformation. The method ID is concatenation of the following:
- The value of the class attribute constant
C_SERVICE_NAME
. - The character
#
. - The description of the API class method for which you need to implement the transformation.
For example, to write transformations for publishing messages to a Pub/Sub topic, the method ID would be:
pubsub:v1#pubsub.projects.topics.publish
- The value of the class attribute constant
In the method implementation of the BAdI:
- For the method ID, write your custom transformation under an
IF….ENDIF block
. Set the exporting parameter
EV_HANDLED
toX
.If
EV_HANDLED
is not set toX
, then the default marshalling and unmarshalling logic of the SDK is applied.
- For the method ID, write your custom transformation under an
Mark the
API State
of the implementing class asUse System-Internally (Contract C1)
. The custom transformation logic is invoked during runtime. The default serialization and deserialization logic shipped with the SDK would be skipped.
Namespace
All Google provided code is placed under the reserved namespace /GOOG/
.
Reference architectures
Explore the ABAP SDK for Google Cloud with the help of the reference architectures and discover how the SDK can bring innovation to your SAP application landscape. You can use the SDK to integrate with Vertex AI for advanced AI and machine learning capabilities, and other Google Cloud services such as BigQuery, Pub/Sub, Cloud Storage and many more. For more information, see Reference architectures for the ABAP SDK for Google Cloud.
Get support
If you need help resolving problems with the ABAP SDK for Google Cloud, then do the following:
Refer to the ABAP SDK for Google Cloud troubleshooting guide.
Ask your questions and discuss ABAP SDK for Google Cloud with the community on Cloud Forums.
Collect all available diagnostic information and contact Cloud Customer Care. For information about contacting Customer Care, see Getting support for SAP on Google Cloud.