تحميل ملف إلى Cloud Storage باستخدام ميزة التقسيم

1. مقدمة

في هذا الدليل التعليمي حول رموز البرامج، لقد أدرجنا خطوات إنشاء حساب خدمة واستخدامه لضبط جدول "مفتاح العميل" و"خريطة الاتصالات" المقدَّمَين من حزمة تطوير البرامج (SDK) لـ ABAP في Google Cloud واستدعاء Cloud Storage JSON API في ABAP.

يتم استخدام خدمات Google Cloud التالية في هذا الدليل التعليمي:

  • Compute Engine
  • خدمات الشبكة
  • Cloud Shell
  • الإصدار 1 من واجهة برمجة التطبيقات JSON في Cloud Storage

ملاحظة: عند إنشاء مشروع جديد على Google Cloud، يتم تلقائيًا تفعيل مجموعة محدّدة من واجهات برمجة التطبيقات والخدمات، بما في ذلك "تخزين السحابة الإلكترونية". يضمن لك ذلك الاستفادة على الفور من حلّ التخزين الفعّال هذا. لذلك، ليس عليك تفعيله كخطوة إضافية.

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

ما ستُنشئه

عليك إنشاء البرامج التالية في نظام SAP باستخدام حزمة تطوير البرامج (SDK) لـ ABAP في Google Cloud.

  • أنشئ حزمة في Cloud Storage.
  • اقرأ ملفًا من خادم التطبيق وحمِّله إلى حزمة Cloud Storage التي تم إنشاؤها.

2. المتطلبات

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

3- قبل البدء

6757b2fb50ddcc2d.png

  • شغِّل الأوامر التالية لمصادقة حسابك وضبط المشروع التلقائي على abap-sdk-poc. تم استخدام المنطقة us-west4-b كمثال. إذا لزم الأمر، يُرجى تغيير المشروع والمنطقة في الأوامر التالية استنادًا إلى إعداداتك المفضّلة.
gcloud auth login
gcloud config set project abap-sdk-poc
gcloud config set compute/zone us-west4-b
  • يجب أن يكون لديك إذن الوصول إلى نظام SAP تم تثبيت حزمة تطوير البرامج (SDK) ABAP عليه في Google Cloud.
  • عليك إكمال الدرس التطبيقي 1 (تثبيت الإصدار التجريبي من منصة ABAP 1909 على Google Cloud Platform وتثبيت حزمة تطوير البرامج (SDK) لـ ABAP على Google Cloud) والدرس التطبيقي 2 (ضبط مصادقة حزمة تطوير البرامج (SDK) لـ ABAP باستخدام الرموز المميّزة لنظام SAP المستضاف على جهاز افتراضي في Compute Engine) قبل المتابعة في هذا الدرس التطبيقي.
  • إذا أكملت ورشةَي التطوير codelab 1 وcodelab 2، كان من المفترض أن يتم توفير نظام ABAP Platform Trial 1909 على Google Cloud، بالإضافة إلى الإعداد المطلوب للمصادقة والاتصال.
  • إذا لم تكن قد أكملت "مختبر الرموز البرمجية" 1 و"مختبر الرموز البرمجية" 2، لن تتوفّر لديك كل البنية الأساسية وإمكانية الاتصال المطلوبة لتنفيذ الخطوات الواردة في "مختبر الرموز البرمجية" هذا. لذلك، عليك إكمال ورشةَي التطوير 1 و2 قبل المتابعة في ورشة التطوير هذه.

4. إنشاء حساب خدمة يتضمّن دور "مستخدم عنصر تخزين"

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

  1. نفِّذ الأمر التالي في وحدة Cloud Shell الطرفية:
gcloud iam service-accounts create abap-sdk-storage-tester \
--display-name="Service Account for Cloud Storage"
  1. أضِف الآن الأدوار المطلوبة إلى حساب الخدمة الذي تم إنشاؤه في الخطوة أعلاه:
gcloud projects add-iam-policy-binding abap-sdk-poc \
--member='serviceAccount:abap-sdk-storage-tester@abap-sdk-poc.iam.gserviceaccount.com' \
--role='roles/storage.objectUser'

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

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

92d75ce1554efb69.png

5- إنشاء إعدادات مفتاح العميل

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

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

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

  1. في واجهة مستخدم SAP، أدخِل رمز المعاملة SPRO.
  2. انقر على SAP Reference IMG.
  3. انقر على حزمة تطوير برامج ABAP لـ Google Cloud ‏ > الإعدادات الأساسية > ضبط مفتاح العميل.
  4. يجب الحفاظ على القيم التالية في الحقول:

الحقل

القيمة

اسم مفتاح Google Cloud

TEST_STORAGE

اسم حساب الخدمة في Google Cloud

abap-sdk-storage-tester@abap-sdk-poc.iam.gserviceaccount.com

نطاق Google Cloud

https://www.googleapis.com/auth/cloud-platform

رقم تعريف المشروع

abap-sdk-poc

فئة التفويض

/GOOG/CL_AUTH_GOOGLE

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

6- إنشاء تقرير Z لإنشاء حزمة على Cloud Storage

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

93f3edb7bbb5c3c4.png

في النافذة المنبثقة التالية، اختَر "عنصر محلي" أو "توفير اسم حزمة" حسب اختيارك.

  1. في "محرر ABAP"، أضِف الرمز التالي:
DATA lv_json_response TYPE string.
DATA ls_input         TYPE /goog/cl_storage_v1=>ty_001.
DATA lo_storage       TYPE REF TO /goog/cl_storage_v1.

TRY.

    lo_storage = NEW #( iv_key_name = 'TEST_STORAGE' ).
        
        " Bucket Name should be globally unique & permanent
    ls_input = VALUE #( name = 'newtest_bucket_abapsdk_gcloud001' ).  
    lo_storage->insert_buckets
                ( EXPORTING iv_q_project = CONV #( lo_storage->gv_project_id )
                    is_input     = ls_input
          IMPORTING es_raw       = lv_json_response
                    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_storage->is_success( lv_ret_code ) = abap_true.
      cl_demo_output=>new(
        )->begin_section( 'Result:'
        )->write_text( 'Bucket was created:'
        )->next_section( 'JSON Response:'
        )->write_json( lv_json_response
        )->display( ).

    ELSE.
      DATA(lv_msg) = lv_ret_code && ':' && lv_err_text.
      cl_demo_output=>new(
        )->begin_section( 'Result:'
        )->write_text( 'Bucket creation failed;'
        )->next_section( 'Error:'
        )->write_json( lv_msg
        )->display( ).
    ENDIF.

  CATCH /goog/cx_sdk INTO DATA(lo_sdk_excp).
    lv_msg = lo_sdk_excp->get_text( ).
    MESSAGE lv_msg TYPE 'S' DISPLAY LIKE 'E'.
ENDTRY.
 

يُرجى العِلم أنّه إذا لم يكن اسم الحزمة فريدًا على مستوى العالم، لن يتم إنشاؤها، لذا حاوِل استخدام اسم فريد للحزمة قبل تنفيذ الرمز.

  1. احفظ التقرير وفعِّله.
  2. تنفيذ التقرير (اضغط على F8).

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

ff232fba9a4178fb.png

7- إنشاء تقرير Z لقراءة ملف من خادم التطبيقات وتحميله إلى حزمة Cloud Storage

قبل تنفيذ هذا النشاط، عليك إعداد ملف نصي كبير. لدينا هنا ملف نصي كبير تم إنشاؤه وتحميله إلى خادم التطبيقات. يمكنك استخدام رمز المعاملة CG3Z لتحميل ملف إلى خادم تطبيقات نظام SAP.

في هذا المثال، نستخدم ملفًا نصيًا بحجم 40 ميغابايت تقريبًا، سبق أن تم تحميله إلى Application Server في الدليل /tmp.

يمكنك أيضًا تنزيل هذا المجلد من GitHub باستخدام الرابط التالي: نموذج الملف

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

19cbe6987bba58e4.png

في النافذة المنبثقة التالية، اختَر "عنصر محلي" أو أدخِل اسم حزمة حسب اختيارك.

  1. في "محرر ABAP"، أضِف الرمز التالي:
DATA lv_file_length TYPE i.
DATA lv_msg         TYPE string.
DATA lv_dset        TYPE string.
DATA lv_data        TYPE string.
DATA ls_data        TYPE xstring.
DATA lo_storage     TYPE REF TO /goog/cl_storage_v1.

" Read file data from the application server
DATA(dset) = '/tmp/sample_file.txt'.
OPEN DATASET dset FOR INPUT IN TEXT MODE ENCODING DEFAULT.
IF sy-subrc <> 0.
  MESSAGE 'Cannot opening/reading dataset' TYPE 'E'.
ENDIF.
DO.
  READ DATASET dset INTO lv_dset.
  IF sy-subrc <> 0.
    EXIT.
  ENDIF.

  CONCATENATE lv_data lv_dset INTO lv_data SEPARATED BY cl_abap_char_utilities=>newline.
  CLEAR lv_dset.

ENDDO.

CLOSE DATASET dset.

CALL FUNCTION 'SCMS_STRING_TO_XSTRING'
  EXPORTING  text   = lv_data
  IMPORTING  buffer = ls_data
  EXCEPTIONS failed = 1
             OTHERS = 2.
IF sy-subrc <> 0.
  MESSAGE 'Conversion from string to xstring failed' TYPE 'E'.
ENDIF.

TRY.

    lo_storage = NEW #( iv_key_name = 'DEMO_STORAGE' ).

    lo_storage->add_common_qparam( iv_name = 'uploadType' iv_value = 'resumable' ).

    lo_storage->insert_objects( EXPORTING iv_q_name       = 'large_text_file_demo.txt'
                                          iv_p_bucket     = 'newtest_bucket_abapsdk_gcloud001'
                                          is_data         = ls_data
                                          iv_content_type = 'text/pdf'
                                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_storage->is_success( lv_ret_code ) = abap_true.
      cl_demo_output=>new(
        )->begin_section( 'Result:'
        )->write_text( 'Object was uploaded successfully'
        )->write_text( 'Object Self Link:'
        )->write_text( ls_output-self_link
        )->display( ).
    ELSE.
      cl_demo_output=>new(
        )->begin_section( 'Error:'
        )->write_text( lv_msg
        )->display( ).
    ENDIF.
  CATCH /goog/cx_sdk INTO data(lo_sdk_excp).
    lv_msg = lo_sdk_excp->get_text( ).
    MESSAGE lv_msg TYPE 'S' DISPLAY LIKE 'E'.
    RETURN.
ENDTRY.

lo_storage->close( ).
  1. احفظ التقرير وفعِّله.
  2. تنفيذ التقرير (اضغط على F8).

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

c982bfcd07d7e487.png

يمكنك التحقّق مما إذا تم تحميل الملف بنجاح أم لا من خلال الانتقال إلى حزمة التخزين في السحابة الإلكترونية كما هو موضّح أدناه.

90678b475e165adf.png

1886be610c63ed6b.png

8. شرح لتحميل ملف إلى Cloud Storage باستخدام رمز حزمة تطوير البرامج (SDK) لـ ABAP

في الأساس، يتم دمج برنامج ABAP هذا مع Google Cloud Storage. يقرأ هذا البرنامج ملفًا من خادم التطبيق ويُرسِل بيانات الملف إلى واجهة برمجة التطبيقات Storage API لتحميلها إلى حزمة تخزين تم إنشاؤها في برنامج إعداد التقارير السابق.

ينفِّذ برنامج التقارير الذي أنشأته لتحميل ملف ما ما يلي:

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

إتمام الاتصال:

  • يُنشئ هذا الإجراء اتصالاً عبر بروتوكول HTTP بخدمة Google Storage باستخدام فئة /GOOG/CL_STORAGE_V1.

قراءة بيانات الملف

  • تقرأ هذه الوظيفة الملف على خادم التطبيقات من خلال إجراء OPEN DATASET، ثم تستدعي وحدة دالة SAP العادية SCMS_STRING_TO_XSTRING للتحويل إلى تنسيق XSTRING.

إضافة مَعلمات طلبات البحث الشائعة

  • لتنفيذ التجزئة، يجب اختيار نوع التحميل "القابل للاستئناف". عند اختيار ميزة "التحميل القابل للاستئناف" تلقائيًا، يتم تقسيم بيانات الملف إلى أجزاء بحجم 8 ميغابايت ويتم تحميلها. ومع ذلك، يمكن للمطوّرين تغيير حجم القطع هذا من خلال ضبط المَعلمة IV_P_CHUNK_SIZE، ولكن يُنصح باستخدام الإعداد التلقائي.
  • لإعلام طريقة واجهة برمجة التطبيقات بضرورة اختيار خيار التحميل "يمكن استئنافه"، نُطلِق على الطريقة ADD_COMMON_QPARAM ونُمرِّر uploadType على أنّه resumable..

إدراج عناصر

  • تستدعي الطريقة INSERT_OBJECTS من خلال تمرير المَعلمات التالية إليها:
  • IV_Q_NAME: اسم الملف الذي سيتم تخزين المحتوى فيه في Cloud Storage
  • IV_P_BUCKET: اسم الحزمة التي يجب تحميل الملف إليها
  • IS_DATA: بيانات الملفات التي يجب تحميلها
  • IV_CONTENT_TYPE: نوع محتوى الملف، في السيناريو الحالي، نستخدم "text/plain" لأنّنا نحمّل ملفًا نصيًا.

يُرجى العِلم أنّنا لا نُمرِّر أي قيمة إلى مَعلمة الاستيراد IV_CHUNK_SIZE ونترك لـ "الرمز المرجعي لعميل واجهة برمجة التطبيقات" استخدام القيمة التلقائية المرتبطة بهذه المَعلمة، وهي 8 ميغابايت.

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

  • تعرِض هذه السمة استجابة واجهة برمجة التطبيقات استنادًا إلى ما إذا كان طلب البيانات من واجهة برمجة التطبيقات ناجحًا أم لا.

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

  • يُغلق هذا الإجراء اتصال HTTP بخدمة التخزين.

9. تهانينا

تهانينا! لقد أكملت بنجاح دورة Codelab حول "تحميل ملف إلى حزمة Cloud Storage".

توفّر Cloud Storage JSON API الكثير من الإمكانات، ومن خلال حزمة تطوير البرامج (SDK) لـ ABAP في Google Cloud، يمكنك الوصول إليها مباشرةً في أنظمة SAP باستخدام ABAP.

تُعدّ Google Cloud Storage خيارًا رائعًا لتخزين الكميات الكبيرة من البيانات وإدارتها. ويستخدمه مجموعة واسعة من الأنشطة التجارية والمؤسسات والتطبيقات.

في ما يلي بعض مزايا استخدام Google Cloud Storage:

  • التكلفة العالية الكفاءة: تُعدّ Google Cloud Storage طريقة عالية الكفاءة لتخزين الكميات الكبيرة من البيانات وإدارتها.
  • البساطة: خدمة Google Cloud Storage سهلة الاستخدام، وتوفّر واجهة برمجة تطبيقات بسيطة وسهلة الاستخدام.
  • المرونة: يمكن استخدام Google Cloud Storage مع مجموعة متنوعة من التطبيقات والأنظمة الأساسية.

يمكنك الآن المتابعة باستخدام رمز التطبيق أدناه لمواصلة رحلتك التعليمية لاستخدام حزمة تطوير البرامج (SDK) ABAP للوصول إلى خدمات Google Cloud المختلفة.

  • إرسال حدث إلى Pub/Sub
  • تلقّي حدث من Cloud Pub/Sub
  • استخدام Cloud Translation API لترجمة النصوص
  • استخدام واجهة برمجة التطبيقات DLP API لمنع ظهور معلومات تحديد الهوية الشخصية
  • استدعاء BigQuery ML من ABAP

10. تَنظيم

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

حذف المشروع

  • يُرجى اتّباع الخطوات التالية لحذف مشروع Google Cloud:
gcloud projects delete abap-sdk-poc

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

  1. حذف وحدة الحوسبة:
gcloud compute instances delete abap-trial-docker
  1. حذف قواعد جدار الحماية:
gcloud compute firewall-rules delete sapmachine
  1. لحذف حساب الخدمة:
gcloud iam service-accounts delete \
    abap-sdk-dev@abap-sdk-poc.iam.gserviceaccount.com