تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تلقّي حدث من Cloud Pub/Sub في SAP باستخدام حزمة تطوير البرامج (SDK) ABAP في Google Cloud

1. مقدمة

يرشدك هذا الدرس التطبيقي إلى كيفية تلقّي تفاصيل الأحداث من موضوع Google Cloud Pub/Sub باستخدام حزمة تطوير البرامج (SDK) ABAP لخدمة Google Cloud. سنستفيد من خدمات Google Cloud التالية:

خدمة Cloud Pub/Sub
Cloud Shell

المتطلبات الأساسية

تأكَّد من إمكانية الوصول إلى نظام SAP مثبَّت عليه حزمة تطوير البرامج (SDK) المستندة إلى لغة ABAP في Google Cloud.
يمكنك الرجوع إلى الدرس التطبيقي تثبيت الإصدار التجريبي من منصة ABAP على Google Cloud Platform وتثبيت حزمة تطوير البرامج (SDK) ABAP لإعداد نظام جديد.
لقد أنشأت موضوعًا PUBSUB_DEMO_TOPIC كجزء من Codelab " إرسال الأحداث من SAP إلى Pub/Sub باستخدام حزمة تطوير البرامج (SDK) الخاصة بلغة ABAP" في مشروع Google Cloud. إذا لم يتم إنشاؤه، استخدِم الأمر أدناه لإنشائه:

gcloud pubsub topics create PUBSUB_DEMO_TOPIC

ما ستنشئه

ستنشئ ما يلي:

حساب خدمة لديه أذونات "مشترك" للتفاعل مع Pub/Sub API
برنامج ABAP لتلقّي الرسائل من موضوع Pub/Sub وتأكيد استلامها

2. المتطلّبات

المتصفحات، مثل Chrome أو Firefox
مشروع Google Cloud تم تفعيل الفوترة فيه أو إنشاء حساب فترة تجريبية مجانية لمدة 90 يومًا على Google Cloud Platform
يجب أن يكون SAP GUI (Windows أو Java) مثبّتًا على نظامك. إذا كان SAP GUI مثبَّتًا على الكمبيوتر المحمول، يمكنك الاتصال بنظام SAP باستخدام عنوان IP الخارجي للجهاز الافتراضي كعنوان IP لخادم التطبيقات. إذا كنت تستخدم جهاز Mac، يمكنك أيضًا تثبيت SAP GUI for Java المتاح في هذا الرابط.

3- قبل البدء

في Google Cloud Console، ضِمن صفحة اختيار المشروع، اختَر أو أنشِئ مشروعًا على Google Cloud (مثلاً: abap-sdk-poc).
تأكَّد من تفعيل الفوترة لمشروعك على Cloud. تعرَّف على كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع. يمكنك تخطّي هذه الخطوة إذا كنت تستخدم حسابًا تجريبيًا مجانيًا لمدة 90 يومًا.
ستستخدم Cloud Shell، وهي بيئة سطر أوامر تعمل في Google Cloud. من Cloud Console، انقر على تفعيل Cloud Shell في أعلى يسار الصفحة:

شغِّل الأوامر التالية للمصادقة على حسابك وضبط المشروع التلقائي على abap-sdk-poc. يتم استخدام المنطقة us-west4-b كمثال. إذا لزم الأمر، يُرجى تغيير المشروع والمنطقة في الأوامر التالية استنادًا إلى إعداداتك المفضّلة.

gcloud auth login
gcloud config set project abap-sdk-poc
gcloud config set compute/zone us-west4-b

في إطار الدرس التطبيقي السابق " إرسال حدث إلى Pub/Sub"، يجب أن تكون قد فعّلت واجهة برمجة التطبيقات Pub/Sub وأنشأت الموضوع ونشرت الرسائل في Pub/Sub.

4. إنشاء حساب خدمة للوصول إلى Pub/Sub

يُعدّ استخدام حساب خدمة لديه دور Subscriber الطريقة الأكثر أمانًا لتلقّي برنامج ABAP الرسائل من Pub/Sub. يقيّد هذا الدور الأذونات على استرداد الرسائل فقط، ما يمنع الثغرات الأمنية المحتملة.

إنشاء حساب الخدمة

لإنشاء حساب خدمة يتضمّن الدور المطلوب، اتّبِع الخطوات التالية:

نفِّذ الأمر التالي في وحدة Cloud Shell الطرفية:

gcloud iam service-accounts \
create abap-sdk-pubsub-subscriber \
--display-name="Service Account for Pub/Sub Subscriber"

الآن، أضِف الأدوار المطلوبة إلى حساب الخدمة الذي تم إنشاؤه في الخطوة أعلاه:

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'

يستخدم الأمر أعلاه abap-sdk-poc كعنصر نائب لمشروع Google Cloud. استبدِل abap-sdk-poc برقم تعريف مشروعك.

للتأكّد من إضافة الدور، انتقِل إلى صفحة IAM. يجب أن يظهر حساب الخدمة الذي أنشأته مع الدور الذي تمّ تعيينه له.

5- التعرّف على الاشتراكات التي يتم سحبها

بالنسبة إلى اشتراك السحب، يعمل نظام SAP كعميل مشترك ويبدأ الطلبات إلى خادم Pub/Sub لاسترداد الرسائل. يستخدم برنامج العميل المشترِك واجهة برمجة تطبيقات REST Pull API.

طُرق واجهة برمجة التطبيقات الرئيسية

Google Cloud Pub/Sub API

pull: يبدأ طلبًا لاسترجاع الرسائل.
acknowledge: إشارات إلى Pub/Sub بأنّه تمت معالجة الرسالة بنجاح.

ABAP SDK for Google Cloud Equivalents

/GOOG/CL_PUBSUB_V1 -> PULL_SUBSCRIPTIONS
/GOOG/CL_PUBSUB_V1 -> ACKNOWLEDGE_SUBSCRIPTIONS

سير الرسائل في اشتراك السحب

تعرض الصورة التالية سير العمل بين جهاز العميل المشترِك والاشتراك في السحب.

طلب السحب: يستخدم نظام SAP (المشترك) طريقة السحب لطلب الرسائل من خادم Pub/Sub.
استجابة السحب: يستجيب خادم Pub/Sub بصفر أو أكثر من الرسائل ومعرّفات الإقرار. لا يشير الردّ الذي يتضمّن صفر رسائل أو خطأ بالضرورة إلى عدم توفّر أي رسائل لتلقّيها. هذا الرد هو PullResponse كما هو موضّح في الصورة.
الإقرار: بعد معالجة رسالة، يستخدم نظام SAP طريقة الإقرار مع رقم تعريف الإقرار الذي تم استلامه. يمنع هذا الإجراء Pub/Sub من إعادة تسليم الرسالة.

6. إعداد الاشتراك وإرسال الرسائل

إنشاء اشتراك سحب

نفِّذ أمر gcloud التالي لإنشاء اشتراك سحب باسم PUBSUB_DEMO_SUBSCRIPTION سيتلقّى رسائل من PUBSUB_DEMO_TOPIC:

gcloud pubsub subscriptions create PUBSUB_DEMO_SUBSCRIPTION \
--topic=PUBSUB_DEMO_TOPIC

نشر الرسائل

اختَر إحدى الطرق التالية لإرسال رسائل إلى PUBSUB_DEMO_TOPIC:

إعادة استخدام برنامجك: إذا كان لديك البرنامج من درس برمجة سابق للنشر، استخدِمه.
النشر المباشر: لإجراء اختبار سريع، جرِّب أحد الخيارَين التاليَين:
‫Cloud Console: يمكنك النشر مباشرةً من داخل Google Cloud Console. لمزيد من التفاصيل، يُرجى الاطّلاع على مستندات Pub/Sub.
أمر gcloud: نفِّذ الأمر التالي:

gcloud pubsub topics publish PUBSUB_DEMO_TOPIC \
--message='{"eventType":"SalesOrderChanged","source":"SAPDEV100","eventTime":"20240207183048","SalesOrder":1000924}'

7. إنشاء إعداد مفتاح العميل

بعد إعداد المتطلبات الأساسية على Google Cloud، يمكننا المتابعة مع عملية الإعداد على SAP.

بالنسبة إلى الإعدادات المتعلّقة بالمصادقة والاتصال، تستخدم حزمة تطوير البرامج (SDK) للغة ABAP في Google Cloud الجدولَين /GOOG/CLIENT_KEY و/GOOG/SERVIC_MAP..

للحفاظ على الإعداد في الجدول /GOOG/CLIENT_KEY، اتّبِع الخطوات التالية:

في SAP GUI، أدخِل رمز المعاملة SPRO.
انقر على SAP Reference IMG.
انقر على حزمة تطوير البرامج (SDK) للغة ABAP على Google Cloud > الإعدادات الأساسية > إعداد مفتاح العميل.

احتفِظ بالقيم التالية في الحقول. اترك جميع الحقول الأخرى فارغة.

الحقل	القيمة
اسم مفتاح Google Cloud	PUBSUB_SUBSCRIBER
اسم حساب خدمة Google Cloud	abap-sdk-pubsub-subscriber@abap-sdk-poc.iam.gserviceaccount.com
نطاق Google Cloud	https://www.googleapis.com/auth/cloud-platform
رقم تعريف المشروع	abap-sdk-poc
فئة التفويض	/GOOG/CL_AUTH_GOOGLE

8. إنشاء تقرير ABAP لتلقّي الرسائل من Google Cloud Pub/Sub

سجِّل الدخول إلى نظام SAP.
انتقِل إلى رمز المعاملة SE38 وأنشئ "برنامج تقارير" بالاسم ZDEMO_RECEIVE_CPS_EVENTS..
في النافذة المنبثقة التي تظهر، أدخِل التفاصيل كما هو موضّح أدناه، ثم انقر على حفظ.

في النافذة المنبثقة التالية، اختَر Local Object (كائن محلي) أو أدخِل اسم حزمة حسب الاقتضاء.
في "أداة تعديل ABAP"، أضِف الرمز التالي:

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.

احفظ التقرير وفعِّله.
نفِّذ التقرير (F8).

عند التنفيذ بنجاح، من المفترض أن تظهر لك نتائج التقرير كما هو موضّح أدناه:

9- شرح رمز المشترك في ABAP Pub/Sub

في الأساس، يتكامل برنامج ABAP هذا مع Google Cloud Pub/Sub كمشترك في الرسائل. يتحقّق من اشتراك محدّد بحثًا عن رسائل جديدة عند الطلب، ويعالجها، ثم يؤكّد استلامها لمنع إعادة تسليمها في المستقبل.

سينفّذ البرنامج الأنشطة التالية:

التحليل المفصّل

إنشاء اتصال:

تنشئ هذه السمة اتصال HTTP بخدمة Google Cloud Pub/Sub باستخدام الفئة /GOOG/CL_PUBSUB_V1.

ضبط المَعلمات:

رقم تعريف المشروع: يستخرج رقم تعريف المشروع ذي الصلة الذي يقع فيه اشتراك Pub/Sub.
اسم الاشتراك: يحدّد اسم الاشتراك الذي سيتم استرداد الرسائل منه (PUBSUB_DEMO_SUBSCRIPTION).
الحدّ الأقصى لعدد الرسائل: يضبط هذا الحقل الحدّ الأقصى لعدد الرسائل التي يمكن استردادها في طلب واحد من واجهة برمجة التطبيقات (في هذه الحالة، 1).

استرداد الرسائل:

يستدعي الطريقة pull_subscriptions لاسترداد الرسائل من الاشتراك المحدّد.

معالجة الرسائل المستلَمة:

إذا كانت الرسائل متوفّرة، يفك البرنامج ترميز البيانات ويسجّل المحتوى ويرسل إقرارًا بالاستلام.

تأكيد استلام الرسائل:

يتم استدعاء الطريقة acknowledge_subscriptions لإرسال إقرار إلى Pub/Sub يشير إلى استلام الرسائل بنجاح. ويمنع ذلك إعادة تسليمها.

التعامل مع النجاح/الأخطاء:

تعرض هذه السمة رسائل النجاح في حال تلقّي الرسائل وتأكيد استلامها، كما تعرض رسائل الخطأ في سيناريوهات الفشل المختلفة (عدم تلقّي الرسائل، وأخطاء واجهة برمجة التطبيقات، وما إلى ذلك).

إغلاق الاتصال:

يُغلِق هذا الإجراء اتصال HTTP بخدمة Pub/Sub.

10. تهانينا

أحسنت إكمال Codelab "تلقّي حدث من Cloud Pub/Sub باستخدام حزمة تطوير البرامج (SDK) للغة ABAP على Google Cloud".

لقد أنشأت جسرًا بنجاح بين ABAP وGoogle Cloud Pub/Sub. يشير إكمال الدرس التطبيقي إلى فهمك الجيد لميزة المراسلة المستندة إلى الأحداث وكيفية استخدام حزمة تطوير البرامج (SDK) ABAP لخدمة Google Cloud من أجل التكامل مع خدمات Google Cloud. أحسنت!

لقد أتحنا مستوى جديدًا من التكامل بين ABAP وخدمات Google Cloud. استكشِف آفاقًا جديدة مع هذه الخيارات الرائعة:

استخدام Translation API مع حزمة تطوير البرامج (SDK) ABAP على Google Cloud
تحميل ملف كبير إلى حزمة Cloud Storage باستخدام تقسيم الملفات
استرداد بيانات الاعتماد/الأسرار من Secret Manager باستخدام حزمة تطوير البرامج (SDK) للغة ABAP في Google Cloud
استدعاء Vertex AI test-bison من ABAP
استدعاء BigQuery ML من ABAP

11. تَنظيم

إذا كنت لا تريد مواصلة استخدام دروس البرمجة الإضافية المتعلّقة بحزمة تطوير البرامج (SDK) للغة ABAP على Google Cloud، يُرجى المتابعة وتنفيذ عملية التنظيف.

حذف المشروع

تنبيه: يؤدي حذف مشروع إلى ما يلي:

يتم حذف كل المحتوى في المشروع. إذا كنت قد استخدمت مشروعًا حاليًا للمهام الواردة في هذا المستند، سيؤدي حذفه إلى حذف أي عمل آخر أنجزته في المشروع.
فقدان أرقام تعريف المشاريع المخصّصة: عند إنشاء هذا المشروع، ربما أنشأت معرّف مشروع مخصّصًا تريد استخدامه في المستقبل. للحفاظ على عناوين URL التي تستخدم رقم تعريف المشروع، مثل عنوان URL appspot.com، احذف الموارد المحدّدة داخل المشروع بدلاً من حذف المشروع بأكمله.

إذا كنت تخطّط لاستكشاف بنى أو أدلة تعليمية أو أدلة تشغيل سريع متعددة، يمكن أن يساعدك إعادة استخدام المشاريع في تجنُّب تجاوز حدود حصص المشاريع.

احذف مشروع Google Cloud باتّباع الخطوات التالية:

gcloud projects delete abap-sdk-poc

حذف موارد فردية

احذف الجهاز الظاهري:

gcloud compute instances delete abap-trial-docker

احذف قواعد جدار الحماية باتّباع الخطوات التالية:

gcloud compute firewall-rules delete sapmachine

احذف حساب الخدمة:

gcloud iam service-accounts delete \
    abap-sdk-pubsub-subscriber@abap-sdk-poc.iam.gserviceaccount.com