تمت ترجمة هذه الصفحة بواسطة 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.
يمكنك الرجوع إلى دورة codelab "تثبيت إصدار ABAP Platform Trial على 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 API وأنشأت الموضوع ونشرت الرسائل في 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 لاسترداد الرسائل. يستخدم برنامج "مشترك Google Play" واجهة برمجة التطبيقات REST Pull API.

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

Google Cloud Pub/Sub API

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

المكافئات لحزمة تطوير البرامج (SDK) لـ ABAP في Google Cloud

‫/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:

إعادة استخدام البرنامج: إذا كان لديك البرنامج من دورة تدريبية سابقة على Codelab للنشر، استخدِمه.
النشر المباشر: لإجراء اختبار سريع، جرِّب أحد الخيارَين التاليَين:
‫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.

بالنسبة إلى الإعدادات ذات الصلة بالمصادقة والاتصال، تستخدم حزمة ABAP SDK لـ Google Cloud الجدولَين /GOOG/CLIENT_KEY و/GOOG/SERVIC_MAP..

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

في واجهة مستخدم SAP، أدخِل رمز المعاملة SPRO.
انقر على SAP Reference IMG.
انقر على حزمة تطوير برامج 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..
في النافذة المنبثقة التي تظهر، أدخِل التفاصيل كما هو موضّح أدناه، ثم انقر على حفظ.

في النافذة المنبثقة التالية، اختَر كائن محلي أو أدخِل اسم حزمة حسب الاقتضاء.
في "محرر 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).
الحد الأقصى للرسائل: يحدِّد الحد الأقصى لعدد الرسائل التي يمكن استرجاعها في طلب واحد لواجهة برمجة التطبيقات (في هذه الحالة، رسالة واحدة).

جلب الرسائل:

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

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

إذا كانت هناك رسائل، يفكّ البرنامج ترميز البيانات ويُسجّل المحتوى ويُرسِل إشعارًا بالاستلام.

الإقرار بالرسائل:

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

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

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

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

يُغلق اتصال HTTP بخدمة Pub/Sub.

10. تهانينا

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

لقد أنشأت بنجاح رابطًا بين ABAP وGoogle Cloud Pub/Sub. يُظهر إكمالك لأحد مشاريع Codelab فهمًا جيدًا للمراسلة المستندة إلى الأحداث وكيفية استخدام حزمة تطوير البرامج (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