Pengembangan aplikasi dengan ABAP SDK edisi SAP BTP untuk Google Cloud

Dokumen ini memberikan informasi dan referensi yang berguna untuk membantu Anda mengembangkan aplikasi SAP menggunakan ABAP SDK edisi SAP BTP untuk Google Cloud.

Dokumen ini dibuat bagi para developer SAP ABAP.

Untuk mengetahui daftar lengkap library klien yang disediakan oleh ABAP SDK untuk Google Cloud edisi SAP BTP, lihat ABAP SDK untuk library klien Google Cloud.

Satu jendela interaksi

Setiap Google Cloud API yang diaktifkan dalam ABAP SDK untuk Google Cloud diwakili oleh kelas ABAP, yang terdapat dalam paket /GOOG/CLIENT. Kelas ABAP terdiri dari beberapa metode publik dan setiap metode publik ini dapat berinteraksi dengan metode Google Cloud API. Setiap metode publik selanjutnya terdiri dari parameter IMPORTING dan parameter EXPORTING. Kelas ABAP juga berisi jenis data khusus, yang dapat digunakan untuk membuat dan memetakan parameter IMPORTING dan EXPORTING. Jenis data kustom ini dipetakan ke definisi skema API.

Pada setiap interaksi dengan Google Cloud API target, kelas ABAP yang terkait berfungsi sebagai satu-satunya titik interaksi. Kami menyebut konsep ini sebagai Interaksi satu jendela yang melindungi developer dari segala kompleksitas interaksi mendasar dengan Google Cloud API dan menghadirkan antarmuka yang disederhanakan. Antarmuka yang disederhanakan ini memungkinkan Anda untuk berfokus pada solusi bisnis yang dikembangkan menggunakan SDK, tanpa perlu mengkhawatirkan fitur SDK yang mendasarinya.

Satu jendela interaksi

Alur interaksi

Untuk memanggil metode API, Anda dapat menjalankan alur interaksi sebagai berikut:

  1. Menghubungkan ke API.
  2. Membuat permintaan input menggunakan jenis ABAP.
  3. Memanggil metode API.
  4. Menguraikan error dan mekanisme pengecualian.
  5. Membaca respons menggunakan jenis ABAP.

Interaksi developer

Stub klien API

Kelas stub klien API standar terdiri dari bagian berikut:

  • Jenis ABAP yang dipetakan ke skema API. Gunakan jenis ABAP untuk membuat permintaan input dan mengurai respons.
  • Konstanta dan atribut untuk penggunaan internal atau eksternal.
  • Metode API untuk berinteraksi dengan resource API.

Struktur kelas

Features

ABAP SDK untuk Google Cloud mencakup fitur berikut:

  • Komunikasi HTTP: SDK membuat koneksi HTTP dengan endpoint API.
  • Request marshaling: SDK mengonversi data dalam jenis ABAP menjadi payload JSON yang dikirim sebagai isi permintaan.
  • Penanganan error dan pengecualian: SDK menangani kode status dan pesan error yang ditampilkan oleh API, dan memunculkan pengecualian, jika ada.
  • Respons membatalkan marshalling: SDK mengonversi kembali payload JSON dalam isi respons menjadi jenis ABAP yang sesuai.
  • Logging error lokal: SDK mencatat pesan error menggunakan framework logging.

Desain API dan Google API Explorer

API yang dipublikasikan oleh Google mengikuti desain yang berorientasi pada resource. Untuk mempelajari desain API Google lebih lanjut, lihat panduan desain API.

ABAP SDK untuk Google Cloud memungkinkan integrasi dengan API berbasis REST yang dipublikasikan oleh Google.

Google API Explorer adalah alat yang memungkinkan Anda mencoba metode Google Cloud API tanpa menulis kode. Anda dapat menggunakan alat ini untuk mempelajari API dan parameter input yang diperlukan yang ingin diteruskan ke metode ABAP yang sesuai.

Konstruksi kode

Menjelaskan konstruksi kode yang Anda gunakan untuk membuat program ABAP menggunakan ABAP SDK untuk Google Cloud.

Konstruktor

Pertama-tama, buat instance kelas API yang ingin Anda gunakan. Konstruktor setiap kelas API akan memiliki pola serupa seperti yang ditunjukkan dalam contoh berikut:

    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

Mengimpor parameter

Tabel berikut menjelaskan parameter impor pada sebuah konstruktor metode:

Nama Parameter Jenis Wajib/Opsional Deskripsi
iv_key_name /GOOG/KEYNAME Diperlukan Tentukan kunci klien dari konfigurasi yang Anda gunakan untuk membuat koneksi ke Google Cloud. Untuk mengetahui informasi tentang konfigurasi kunci klien, lihat Autentikasi.
iv_log_object balobj_d Opsional Tentukan objek log aplikasi, yang Anda gunakan untuk menyimpan error yang dihasilkan SDK. Untuk mengetahui informasi tentang konfigurasi logging, lihat Logging aplikasi.
iv_log_subobject balsubobj Opsional Tentukan subobjek log aplikasi, yang Anda gunakan untuk menyimpan error yang dihasilkan SDK. Untuk mengetahui informasi tentang konfigurasi logging, lihat Logging aplikasi.

Metode API

Dengan desain Google Cloud API yang berorientasi resource, metode API adalah tindakan yang dapat dilakukan pada resource yang dipublikasikan oleh API.

Misalnya, jika Topics adalah resource yang dipublikasikan oleh Pub/Sub API, topics.get adalah metode API yang mewakili tindakan pada resource Topics untuk mendapatkan konfigurasi topik.

Untuk memetakan metode kelas ABAP ke metode API, Anda dapat melihat deskripsi metode yang mengikuti pola:<resource>.<method_verb>.

Misalnya, deskripsi metode untuk metode Pub/Sub adalah pubsub.projects.topics.get.

  • projects.topics: nama resource.
  • get: tindakan metode.

UI SAP deskripsi metode

Nama pada pemetaan metode ABAP ke tindakan API mengikuti pola:<method_verb>_<resource>.

Misalnya, nama metode ABAP untuk Pub/Sub adalah: GET_TOPICS

  • GET: tindakan metode.
  • TOPICS: nama resource.

Metode ABAP terdiri dari bagian berikut yang dipetakan ke metode REST API:

Nama metode

Mengimpor parameter

Metode API dapat memiliki parameter impor berikut. Parameter ini bersifat opsional dan Anda dapat meneruskan parameter berdasarkan persyaratan metode API yang perlu digunakan.

Nama Parameter Jenis Kategori Deskripsi

iv_q_NAME

(0 hingga n)

 String Parameter kueri

Parameter kueri ditambahkan ke endpoint API setelah (?).

Parameter ini digunakan untuk mendefinisikan pengurutan, penomoran halaman, atau filter.

Parameter kuerinya bisa jadi adalah 0 hingga n.

iv_p_NAME

(0 hingga n)

 String Parameter lokasi

Parameter jalur adalah bagian dari endpoint.

Parameter ini digunakan untuk menunjuk ke resource REST API tertentu.

Parameter jalurnya bisa jadi adalah 0 hingga n.

is_input

(0 hingga 1)

TY_CODE (Jenis kelas)

 Parameter struktur input

Data yang diteruskan sebagai isi permintaan dapat dipetakan menggunakan struktur input.

REST API menerima payload JSON sebagai isi permintaan. Parameter ini adalah parameter yang berjenis lengkap yang dikonversi menjadi payload JSON untuk kelas API dan developer tidak diwajibkan untuk menggunakan JSON.

Anda dapat melihat jenis kelas yang tersedia guna memahami jenis ABAP untuk memetakan data. Misalnya, Jenis /GOOG/CL_PUBSUB_V1=>TY_041 dipetakan ke Resource REST: Topic, yang diteruskan sebagai Payload JSON ke metode CREATE_TOPICS.

Suatu metode dapat memiliki maksimal satu parameter isi permintaan. Beberapa metode tidak memiliki isi permintaan.

Mengekspor parameter

Metode API mendukung parameter ekspor berikut:

Nama Parameter Jenis Kategori Deskripsi
es_raw data Output mentah

Parameter ini menyimpan respons JSON (Error atau Berhasil) yang ditampilkan oleh metode API. Petakan parameter ini ke variabel jenis String untuk menerima string respons JSON.

Jika respons berasal dari jenis lain, misalnya, xstring untuk output file dalam /goog/cl_storage_v1->get_objects( ), parameter akan menampilkan nilai yang sesuai.

Gunakan parameter ini untuk skenario pemecahan masalah lanjutan atau untuk skenario API lanjutan.
es_output TY_CODE (Jenis Kelas) Struktur output

Respons JSON dideserialisasi ke struktur ABAP dan ditampilkan menggunakan parameter ekspor yang berjenis ini.

Anda dapat menggunakannya sebagai cara utama untuk membaca respons API menggunakan konstruksi ABAP.
ev_ret_code I (Bilangan Bulat) Kode status

Kode status yang dapat Anda gunakan untuk memverifikasi apakah eksekusi metode API berhasil menjalankan fungsinya.

Untuk mengetahui informasi selengkapnya, lihat kode untuk menampilkan, error, dan pengecualian API.
ev_err_text String Teks Error

Jika panggilan metode gagal, parameter ini akan berisi pesan error yang Anda gunakan untuk mengetahui alasan kegagalan.

Untuk informasi selengkapnya, lihat Kode status, error, dan pengecualian API.
ev_err_resp
  • Jenis error = CHAR 60
  • Deskripsi error = STRING
 Respons error

Parameter ini memberikan informasi tambahan tentang error tersebut.

Untuk mengetahui informasi selengkapnya, lihat kode untuk menampilkan, error, dan pengecualian API.

Jenis kelas

Google Cloud API menggunakan JSON sebagai format utama untuk pertukaran data. ABAP SDK untuk Google Cloud menyediakan jenis ABAP yang dipetakan ke skema JSON yang diharapkan oleh Google Cloud API.

Jenis ABAP ini dan jenis tabel terkait tersedia sebagai jenis kelas di setiap kelas API yang disediakan SDK.

Contoh berikut menunjukkan jenis kelas untuk kelas Pub/Sub API /GOOG/CL_PUBSUB_V1.

Jenis kelas

Deskripsi jenis kelas TY_041 pada bagian /GOOG/CL_PUBSUB_V1 dipetakan ke Resource REST, Topic, yang diteruskan sebagai Payload JSON ke metode CREATE_TOPICS.

Komentar ABAP Doc ditambahkan ke semua kelas API klien. Saat menggunakan ABAP Development Tools untuk SAP NetWeaver (ADT) pada pengembangan, komentar ini memberi Anda deskripsi jenis kelas.

Kode status, error, dan pengecualian API

Jika terjadi error saat metode API kelas ABAP dipanggil, ABAP SDK untuk Google Cloud akan meneruskan informasi error ke program pemanggil menggunakan parameter ekspor SDK atau dengan menampilkan pengecualian.

Nama respons yang ditampilkan

Kode status dan error API

Google Cloud API menggunakan model error yang menawarkan pengalaman konsisten di berbagai API. Saat metode Google Cloud API dipanggil dari SDK, parameter berikut akan berisi kode status API dan pesan:

  • ev_ret_code: kode status atau kode error dalam respons yang diberikan.

  • ev_error_text: pesan error dalam respons yang diberikan, jika ada.

  • es_raw: respons error mentah, jika panggilan metode API gagal.

Untuk memeriksa status panggilan API, gunakan metode IS_SUCCESS. Anda dapat menggunakan nilai ev_ret_code untuk menentukan apakah panggilan API berhasil atau tidak. Secara umum, jika ev_ret_code = 2XX, panggilan metode dianggap berhasil. Untuk semua nilai lainnya, panggilan metode dianggap tidak berhasil.

IF lo_client->is_success( ev_ret_code ).
   "Success: Implement custom code
   ELSE
   "Handle the HTTP error status code
ENDIF.

Untuk beberapa API Google Maps Platform, jika Anda memanggil API dengan input yang tidak valid, API akan menampilkan kode status keberhasilan HTTP 2XX bersama pesan error dan status error, bukan kode status error HTTP (4XX atau 5XX). Pesan error dan status error dalam respons API ini dapat membantu Anda memecahkan masalah dan memperbaiki input yang tidak valid.

Untuk API Google Maps Platform tersebut, selain kode tampilan ev_ret_code, periksa pesan error dan status error yang ditampilkan dalam respons API dengan memanggil metode IS_STATUS_OK setelah panggilan API. Cuplikan berikut menunjukkan contoh cara menggunakan metode IS_STATUS_OK:

IF lo_client->is_status_ok( ).
  "Success: Implement custom code
  ELSE
  "Handle the HTTP error status code
ENDIF.

Parameter es_err_resp memberikan informasi tambahan tentang error tersebut. Tabel berikut menjelaskan kolom di parameter es_err_resp.

Kolom Nilai
es_err_resp-error_description Pesan error yang diterima dari API. Nilai ini sama dengan parameter ev_error_text.
es_err_resp-error Deskripsi status HTTP yang ditampilkan dari klien HTTP SAP.

Menangani error yang ditampilkan oleh Google Cloud API

Gunakan panduan berikut untuk menangani error yang ditampilkan oleh API Google Cloud:

  • Kode error umum: Untuk mengetahui informasi tentang error umum yang ditampilkan oleh Google Cloud API beserta penyebabnya, lihat kode error.

  • Ambil peristiwa error mendetail: Untuk mengambil informasi error mendetail dengan ABAP SDK untuk Google Cloud, gunakan parameter ekspor es_raw dari metode class SDK dan petakan parameter ini ke variabel jenis String. Variabel ini menyimpan respons JSON yang berisi pesan error mendetail dan pelanggaran tertentu yang dialami oleh API.

  • Lihat error mendetail: Untuk melihat informasi error yang mendetail, gunakan salah satu metode berikut:

    • Debugger: Melihat konten variabel yang menyimpan respons JSON dalam alat debugger ABAP untuk analisis lebih lanjut.

    • SAP GUI: Gunakan class ABAP cl_demo_output=>display( lv_response ) untuk representasi visual error dalam program laporan. Jika Anda menggunakan metode API dalam program laporan dan eksekusi program berada dalam mode latar depan, gunakan class ABAP cl_demo_output=>display_json( lv_response ).

      Cuplikan kode berikut mengilustrasikan cara menampilkan respons API jika terjadi 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.

  • Dokumentasi khusus API: Beberapa Google Cloud API memberikan informasi error yang mendetail dan panduan pemecahan masalah dalam dokumentasinya masing-masing. Untuk mengatasi error yang terkait dengan API, lihat dokumentasi khusus untuk API tersebut, misalnya, Pub/Sub, Document AI, dan Cloud Storage.

Pengecualian

Jika terjadi error yang tidak terduga selama panggilan metode API, seperti konfigurasi SDK yang salah atau kegagalan komunikasi HTTP, SDK akan memunculkan pengecualian kelas untuk jenis /GOOG/CX_SDK. Anda harus menangkap pengecualian ini dalam kode dan menulis logika penanganan error yang sesuai.

Menangani pengecualian

Anda bisa mendapatkan pesan error dengan memanggil metode get_text dari kelas pengecualian. Pesan error yang ditampilkan oleh kelas pengecualian memiliki format berikut:

/GOOG/MSG : Return_Code - Error_Message

Penyebab error dan langkah penyelesaian bergantung pada nilai Return_Code.

Nilai Return_Code Penyebab error Resolusi
461 ABAP SDK untuk Google Cloud menggunakan kode status khusus, 461, untuk menginformasikan bahwa langkah penginstalan dan konfigurasi tertentu tidak dilakukan atau tidak diselesaikan dengan benar. Error_Message yang sesuai memberikan detail error selengkapnya. Anda harus meninjau dengan cermat petunjuk penginstalan dan konfigurasi untuk SDK, serta memastikan semuanya dilakukan dengan benar.
Nilai lainnya Kode status ini adalah error HTTP terakhir dari kelas Klien HTTP SAP standar. Error ini menandakan bahwa SAP ICM mengalami masalah komunikasi saat memanggil metode REST API Google. Anda harus meninjau setelan jaringan, firewall, dan SAP ICM dengan cermat, dan memastikan konfigurasi tersebut mengizinkan panggilan HTTP ke Google Cloud API.

Untuk mengetahui pesan error umum yang dipicu di ABAP SDK untuk Google Cloud dan resolusinya, lihat panduan pemecahan masalah.

Logging

Dengan ABAP SDK edisi SAP BTP untuk Google Cloud, Anda dapat mencatat pesan error ke dalam log menggunakan framework logging tersemat. Objek log /GOOG/LOG_OBJECT dan subobjek /GOOG/LOG_SUBOBJECT dikirimkan dengan SDK yang dapat Anda gunakan untuk membuat konfigurasi log default. Untuk mengetahui informasi selengkapnya mengenai cara membuat konfigurasi log default, lihat Mengonfigurasi logging.

Anda dapat melihat log aplikasi menggunakan aplikasi Google SDK:Application Logs Display. Untuk informasi selengkapnya, baca Melihat log.

Pemetaan jenis data

Tabel berikut berisi daftar lengkap nilai type dan format yang didukung oleh Google API Discovery Service dan jenis data ABAP yang sesuai.

Untuk informasi selengkapnya tentang nilai type dan format yang didukung oleh Google API Discovery Service, lihat Ringkasan jenis dan format.

Nilai jenis Nilai format Jenis data ABAP Arti
apa pun TYPE REF TO DATA Properti dapat memiliki jenis apa pun. Ditentukan oleh spesifikasi Skema JSON.
array TABLE TYPE WITH NON UNIQUE KEYS Array nilai JavaScript. Properti item menunjukkan skema untuk nilai array. Ditentukan oleh spesifikasi Skema JSON.
boolean ABAP_BOOLEAN Nilai boolean, bisa "true" atau "false". Ditentukan oleh spesifikasi Skema JSON.
bilangan bulat int32 INT4 Bilangan bulat 32-bit bertanda. Bilangan ini memiliki nilai minimum -2.147.483.648 dan nilai maksimum 2.147.483.647 (inklusif).
bilangan bulat uint32 INT4 Bilangan bulat 32-bit tanpa tanda. Bilangan ini memiliki nilai minimum 0 dan nilai maksimum 4.294.967.295 (inklusif).
angka double /GOOG/NUM_DOUBLE (string) Floating point IEEE 754 64-bit presisi ganda.
angka float /GOOG/NUM_FLOAT (string) Floating point IEEE 754 32-bit presisi tunggal.
objek TYPES Objek JavaScript. Ditentukan oleh spesifikasi Skema JSON.
string STRING String arbitrer. Ditentukan oleh spesifikasi Skema JSON.
string byte STRING String byte dengan padding berenkode base64, yang dienkode dengan URL dan alfabet aman bagi nama file (terkadang disebut sebagai "web-safe" atau "base64url"). Ditentukan oleh RFC 4648.
string tanggal STRING Tanggal RFC 3339 dalam format YYYY-MM-DD. Ditentukan dalam spesifikasi Skema JSON.
string date-time STRING Stempel waktu RFC 3339 dalam waktu UTC. Formatnya adalah yyyy-MM-ddTHH:mm:ss.SSSZ. Bagian milidetik (".SSS") bersifat opsional. Ditentukan dalam spesifikasi Skema JSON.
string google-datetime STRING Stempel waktu RFC 3339 dalam waktu UTC. Formatnya adalah yyyy-MM-ddTHH:mm:ss.SSSZ. Bagian milidetik (".SSS") bersifat opsional.
string google-duration STRING String diakhiri dengan akhiran "s" (menunjukkan detik) dan didahului dengan jumlah detik, dengan nanodetik yang dinyatakan sebagai detik pecahan. Titik selalu digunakan sebagai titik desimal, bukan koma.
string google-fieldmask STRING String dengan nama kolom yang dipisahkan dengan koma. Nama kolom
direpresentasikan dalam konvensi penamaan lower-camel.
string int64 STRING Bilangan bulat 64-bit bertanda. Nilai ini memiliki nilai minimum -9.223.372.036.854.775.808 dan nilai maksimum 9.223.372.036.854.775.807 (inklusif).
string uint64 STRING Bilangan bulat 64-bit tanpa tanda. Bilangan ini memiliki nilai minimum 0 dan nilai maksimum (2^64)-1 (inklusif).

Serialisasi dan deserialisasi permintaan dan respons API

Secara default, ABAP SDK edisi SAP untuk Google Cloud menangani marshalling dan unmarshalling permintaan dan respons API. Setiap class ABAP untuk Google Cloud API telah menyematkan jenis ABAP untuk membentuk input dan output metode. Untuk menerapkan transformasi khusus permintaan dan respons, Anda dapat menggunakan titik peningkatan dengan definisi Add In Bisnis (BAdI) SAP yang dikirimkan dengan SDK.

Mengimplementasikan transformasi kustom

Spot peningkatan /GOOG/ES_TRANSFORM_JSON, yang dikirim dengan SDK, menyertakan definisi BAdI berikut:

  • /GOOG/BADI_SERIALIZE_JSON: untuk menerapkan logika serialisasi kustom.
  • /GOOG/BADI_DESERIALIZE_JSON: untuk mengimplementasikan logika deserialisasi kustom.

Anda dapat menulis logika transformasi tertentu dalam penerapan BAdI ini. Antarmuka BAdI ini memiliki IV_METHOD_NAME sebagai parameter impor. Anda menggunakan parameter ini untuk memisahkan logika transformasi untuk setiap metode API dan API menggunakan blok IF….ENDIF. Di blok penerapan, tetapkan parameter ekspor EV_HANDLED ke X.

Untuk menerapkan transformasi kustom, ikuti langkah-langkah berikut:

  1. Untuk /GOOG/BADI_SERIALIZE_JSON, buat implementasi peningkatan kualitas:

    • Untuk mengubah permintaan API, buat implementasi untuk /GOOG/BADI_SERIALIZE_JSON BAdI dengan class implementasi.
    • Untuk mengubah respons API, buat implementasi untuk /GOOG/BADI_DESERIALIZE_JSON BAdI dengan class implementasi.

  2. Tentukan ID metode dari metode API yang transformasinya perlu Anda tulis. ID metode adalah penyambungan dari hal berikut:

    • Nilai konstanta atribut class C_SERVICE_NAME.
    • Karakter #
    • Deskripsi metode class API yang perlu Anda gunakan untuk mengimplementasikan transformasi.

    Misalnya, untuk menulis transformasi untuk memublikasikan pesan ke topik Pub/Sub, ID metodenya adalah: pubsub:v1#pubsub.projects.topics.publish

  3. Dalam implementasi metode BAdI:

    1. Untuk ID metode, tulis transformasi kustom Anda di bagian IF….ENDIF block.

    2. Tetapkan parameter ekspor EV_HANDLED ke X.

      Jika EV_HANDLED tidak ditetapkan ke X, logika marshalling dan unmarshalling default SDK akan diterapkan.

  4. Tandai API State dari class penerapan sebagai Use System-Internally (Contract C1). Logika transformasi kustom dipanggil selama runtime. Logika serialisasi dan deserialisasi default yang dikirimkan dengan SDK akan dilewati.

Namespace

Semua kode yang disediakan Google ditempatkan di namespace /GOOG/ yang dicadangkan.

Dapatkan dukungan

Jika Anda memerlukan bantuan untuk menyelesaikan masalah terkait ABAP SDK untuk Google Cloud, lakukan hal berikut: