About this codelab
1. Introduction
This codelab guides you through receiving event details from a Google Cloud Pub/Sub topic using the ABAP SDK for Google Cloud. We'll leverage the following Google Cloud services:
- Cloud Pub/Sub
- Cloud Shell
Prerequisites
- Ensure that you have access to a SAP system with ABAP SDK for Google Cloud installed.
- You can refer to codelab " Install ABAP Platform Trial on Google Cloud Platform and Install ABAP SDK" to set up a new system.
- You have created a topic
PUBSUB_DEMO_TOPIC
as a part of Codelab " Send events from SAP to Pub/Sub using ABAP SDK" in your Google Cloud Project. If not created, use below command to create the same:
gcloud pubsub topics create PUBSUB_DEMO_TOPIC
What you'll build
You'll create the following:
- A service account with ‘Subscriber' permissions for interacting with the Pub/Sub API.
- An ABAP program to receive and acknowledge messages from your Pub/Sub topic.
2. Requirements
- Browsers, like Chrome or Firefox.
- A Google Cloud project with billing enabled or Create a 90-Day Free Trial account for Google Cloud Platform.
- SAP GUI (Windows or Java) installed in your system. If SAP GUI is already installed on your laptop, connect to SAP using the VM external IP address as the Application Server IP. If you are on Mac, then you can also install the SAP GUI for Java available in this link.
3. Before you begin
- In the Google Cloud Console, on the project selector page, select or create a Google Cloud project (For example:
abap-sdk-poc
). - Ensure billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project. Skip this step if you are using the 90-Day Free Trial Account.
- You will use Cloud Shell, a command-line environment running in Google Cloud. From the Cloud Console, click Activate Cloud Shell on the top right corner:
- Run the following commands to authenticate for your account and set the default project to
abap-sdk-poc
. Zoneus-west4-b
is used as an example. If needed, please change the project and zone in the following commands based on your preference.
gcloud auth login
gcloud config set project abap-sdk-poc
gcloud config set compute/zone us-west4-b
- As a part of the previous codelab " Send event to Pub/Sub", you must have already enabled the pub/sub API, created the topic and published messages to Pub/Sub.
4. Create a service account for Pub/Sub access
Using a service account with the Subscriber
role is the most secure way for your ABAP program to receive messages from Pub/Sub. This role limits permissions to message retrieval only, preventing potential security vulnerabilities.
Create the Service Account
To create a service account with required role, perform the following steps:
- Run the following command in the Cloud Shell terminal:
gcloud iam service-accounts \
create abap-sdk-pubsub-subscriber \
--display-name="Service Account for Pub/Sub Subscriber"
- Now add the required roles to the service account created in the above step:
gcloud projects add-iam-policy-binding abap-sdk-poc \
--member='serviceAccount:abap-sdk-pubsub-subscriber@abap-sdk-poc.iam.gserviceaccount.com' \
--role='roles/pubsub.subscriber'
The above command uses abap-sdk-poc
as a placeholder for the Google Cloud Project. Replace abap-sdk-poc
with your project id.
- To verify, the role has been added, go to IAM page. The service account you created should be listed along with the role that has been assigned to it.
5. Understanding pull subscriptions
For a pull subscription, your SAP system acts as the subscriber client and initiates requests to a Pub/Sub server to retrieve messages. The subscriber client uses REST Pull API.
Key API methods
Google Cloud Pub/Sub API
- pull: Initiates a request to fetch messages.
- acknowledge: Signals to Pub/Sub that a message has been processed successfully.
ABAP SDK for Google Cloud Equivalents
- /GOOG/CL_PUBSUB_V1 -> PULL_SUBSCRIPTIONS
- /GOOG/CL_PUBSUB_V1 -> ACKNOWLEDGE_SUBSCRIPTIONS
Flow of messages for a pull subscription
The following image shows the workflow between a subscriber client and a pull subscription.
- Pull Request: Your SAP system (the subscriber) uses the pull method to request messages from the Pub/Sub server.
- Pull Response: The Pub/Sub server responds with zero or more messages and acknowledgment IDs. A response with zero messages or with an error does not necessarily indicate that there are no messages available to receive. This response is the PullResponse as shown in the image.
- Acknowledgement: After processing a message, your SAP system uses the acknowledge method along with the received acknowledgment ID. This prevents Pub/Sub from redelivering the message.
6. Setting up your subscription and sending messages
Create a Pull Subscription
- Execute this gcloud command to create a pull subscription named
PUBSUB_DEMO_SUBSCRIPTION
that will receive messages from thePUBSUB_DEMO_TOPIC
:
gcloud pubsub subscriptions create PUBSUB_DEMO_SUBSCRIPTION \
--topic=PUBSUB_DEMO_TOPIC
Publish Messages
Choose one of these methods to send messages to PUBSUB_DEMO_TOPIC
:
- Reuse your program: If you have the program from a previous codelab for publishing, use that.
- Direct Publishing: For a quick test, try one of the following options:
- Cloud Console: Publish directly within the Google Cloud Console. For more details, see Pub/Sub documentation.
- gcloud command: Run the following command:
gcloud pubsub topics publish PUBSUB_DEMO_TOPIC \
--message='{"eventType":"SalesOrderChanged","source":"SAPDEV100","eventTime":"20240207183048","SalesOrder":1000924}'
7. Create client key configuration
Now that you have set up the pre-requisites on the Google Cloud side, we can move ahead with the configuration on the SAP side.
For authentication and connectivity related configuration, the ABAP SDK for Google Cloud uses the tables /GOOG/CLIENT_KEY
and /GOOG/SERVIC_MAP.
To maintain the configuration in the table /GOOG/CLIENT_KEY
table, perform the following steps:
- In the SAP GUI, enter transaction code SPRO.
- Click SAP Reference IMG.
- Click ABAP SDK for Google Cloud > Basic Settings > Configure Client Key.
- Maintain the following values against the fields. Leave all other fields blank.
Field | Value |
Google Cloud Key Name | PUBSUB_SUBSCRIBER |
Google Cloud Service Account Name | abap-sdk-pubsub-subscriber@abap-sdk-poc.iam.gserviceaccount.com |
Google Cloud Scope | https://www.googleapis.com/auth/cloud-platform |
Project ID | abap-sdk-poc |
Authorization Class | /GOOG/CL_AUTH_GOOGLE |
8. Build an ABAP report to receive messages from Google Cloud Pub/Sub
- Log in to your SAP system.
- Go to transaction code
SE38
and create a Report Program with the nameZDEMO_RECEIVE_CPS_EVENTS.
- In the pop-up that opens up, provide details as shown below, and click Save.
- In the next pop-up, either select Local Object or provide a package name as appropriate.
- In the ABAP Editor, add the following code:
REPORT zdemo_receive_cps_events. TYPES: BEGIN OF ty_event_message, event_time TYPE timestamp, event_type TYPE char30, source TYPE char30, sales_order TYPE vbeln, END OF ty_event_message. DATA: ls_input TYPE /goog/cl_pubsub_v1=>ty_026, ls_input_ack TYPE /goog/cl_pubsub_v1=>ty_001, ls_event_msg TYPE ty_event_message. TRY. "Open HTTP Connection DATA(lo_client) = NEW /goog/cl_pubsub_v1( iv_key_name = 'PUBSUB_SUBSCRIBER' ). "Populate relevant parameters " Derive project id from the client object DATA(lv_p_projects_id) = CONV string( lo_client->gv_project_id ). " Name of the subscription from where we want to pull data DATA(lv_p_subscriptions_id) = CONV string( 'PUBSUB_DEMO_SUBSCRIPTION' ). " Max number of messages that will be received in 1 API call ls_input-max_messages = 1. "Call API method: pubsub.projects.subscriptions.pull lo_client->pull_subscriptions( EXPORTING iv_p_projects_id = lv_p_projects_id iv_p_subscriptions_id = lv_p_subscriptions_id is_input = ls_input IMPORTING es_output = DATA(ls_output) ev_ret_code = DATA(lv_ret_code) ev_err_text = DATA(lv_err_text) es_err_resp = DATA(ls_err_resp) ). IF lo_client->is_success( lv_ret_code ). DATA(ls_received_msg) = VALUE #( ls_output-received_messages[ 1 ] OPTIONAL ). IF ls_received_msg IS NOT INITIAL. "Messages published to Pub/Sub should be base-64 encoded, hence in order to get the exact message, we need to decode the data field. "However, attributes published to Pub/Sub should be accessible as data references. DATA(lv_msg) = |{ cl_http_utility=>decode_base64( encoded = ls_received_msg-message-data ) }|. /ui2/cl_json=>deserialize( EXPORTING json = lv_msg pretty_name = /ui2/cl_json=>pretty_mode-extended CHANGING data = ls_event_msg ). cl_demo_output=>new( )->begin_section( |Receive Events from Cloud Pubsub using ABAP SDK for Google Cloud| )->write_text( |The below event was successfully received with message ID { ls_received_msg-message-MESSAGE_ID }| )->write_data( ls_event_msg )->end_section( )->display( ). ls_input_ack-ack_ids = VALUE #( ( ls_received_msg-ack_id ) ). "Call API method: pubsub.projects.subscriptions.acknowledge "Acknowledge the messages so it is not pulled again. lo_client->acknowledge_subscriptions( EXPORTING iv_p_projects_id = lv_p_projects_id iv_p_subscriptions_id = lv_p_subscriptions_id is_input = ls_input_ack IMPORTING es_output = DATA(ls_output_ack) ev_ret_code = lv_ret_code ev_err_text = lv_err_text es_err_resp = ls_err_resp ). IF lo_client->is_success( lv_ret_code ). MESSAGE lv_msg TYPE 'S'. ELSE. MESSAGE lv_err_text TYPE 'E'. ENDIF. ELSE. MESSAGE 'No Messages were received!' TYPE 'S'. ENDIF. ELSE. MESSAGE lv_err_text TYPE 'E'. ENDIF. "Close HTTP Connection lo_client->close( ). CATCH /goog/cx_sdk INTO DATA(lo_exception). MESSAGE lo_exception->get_text( ) TYPE 'E'. ENDTRY.
- Save and activate the Report.
- Execute the report (F8).
On successful execution you should see the report output as shown below:
9. ABAP Pub/Sub subscriber code explained
In essence, this ABAP program integrates with Google Cloud Pub/Sub as a message subscriber. It checks a specified subscription for new messages on demand, processes them, and then acknowledges their reception to prevent future redelivery.
The program will do the following activities:
Step-by-Step breakdown
Establish Connection:
- It establishes an HTTP connection to the Google Cloud Pub/Sub service using the
/GOOG/CL_PUBSUB_V1
class.
Set Parameters:
- Project ID: Extracts the relevant Project ID where the Pub/Sub subscription resides.
- Subscription Name: Specifies the name of the Subscription from which to pull messages (
PUBSUB_DEMO_SUBSCRIPTION
). - Message Limit: Sets the maximum number of messages to retrieve in a single API call (in this case, 1).
Fetch Messages:
- Calls the
pull_subscriptions
method to retrieve messages from the specified subscription.
Process Received Messages:
- If messages exist, the program decodes the data, logs the content, and sends an acknowledgment.
Acknowledge Messages:
- Calls the
acknowledge_subscriptions
method to send an acknowledgment to Pub/Sub indicating successful receipt of the messages. This prevents them from being redelivered.
Handle Success/Errors:
- Provides success messages if messages are received and acknowledged and displays error messages for various failure scenarios (no messages received, API errors, etc.).
Close Connection:
- Closes the HTTP connection to the Pub/Sub service.
10. Congratulations
Excellent work completing the "Receive an event from Cloud Pub/Sub using ABAP SDK for Google Cloud" Codelab!
You've successfully built a bridge between ABAP and Google Cloud Pub/Sub! Your codelab completion demonstrates a solid grasp of event-driven messaging and how to use the ABAP SDK for Google Cloud to integrate with Google Cloud services. Well done!
You've unlocked a new level of integration between ABAP and Google Cloud Services. Expand your horizons with these exciting options:
- Using the Translation API with ABAP SDK for Google Cloud
- Upload a large object to a Cloud Storage bucket using chunking
- Retrieving Credentials/Secrets from Secret Manager with ABAP SDK for Google Cloud
- Call Vertex AI test-bison from ABAP
- Call BigQuery ML from ABAP
11. Clean up
If you do not wish to continue with the additional codelabs related to ABAP SDK for Google Cloud, please proceed with the cleanup.
Delete the project
- Delete the Google Cloud project:
gcloud projects delete abap-sdk-poc
Delete individual resources
- Delete the compute instance:
gcloud compute instances delete abap-trial-docker
- Delete the firewall rules:
gcloud compute firewall-rules delete sapmachine
- Delete the service account:
gcloud iam service-accounts delete \
abap-sdk-pubsub-subscriber@abap-sdk-poc.iam.gserviceaccount.com