Memperluas Datastore dengan Cloud Functions (generasi ke-2)

Dengan Cloud Functions dan Eventarc, Anda dapat men-deploy kode untuk menangani peristiwa yang dipicu oleh perubahan pada database Firestore dalam mode Datastore. Dengan demikian, Anda dapat menambahkan fungsi sisi server tanpa harus menjalankan server Anda sendiri.

Pemicu mode Datastore

Eventarc mendukung pemicu peristiwa Firestore dalam mode Datastore berikut untuk memungkinkan Anda membuat pengendali Cloud Functions (generasi ke-2) yang terkait dengan Firestore dalam peristiwa mode Datastore:

Jenis Peristiwa	Pemicu
`google.cloud.datastore.entity.v1.created`	Dipicu saat entity ditulis untuk pertama kalinya.
`google.cloud.datastore.entity.v1.updated`	Dipicu saat entitas sudah ada dan nilainya berubah.
`google.cloud.datastore.entity.v1.deleted`	Dipicu saat entitas dihapus.
`google.cloud.datastore.entity.v1.written`	Dipicu saat `created`, `updated`, atau `deleted` dipicu.
`google.cloud.datastore.entity.v1.created.withAuthContext`	Sama seperti `created` tetapi menambahkan informasi autentikasi.
`google.cloud.datastore.entity.v1.updated.withAuthContext`	Sama seperti `updated` tetapi menambahkan informasi autentikasi.
`google.cloud.datastore.entity.v1.deleted.withAuthContext`	Sama seperti `deleted` tetapi menambahkan informasi autentikasi.
`google.cloud.datastore.entity.v1.written.withAuthContext`	Sama seperti `written` tetapi menambahkan informasi autentikasi.

Pemicu peristiwa mode Datastore hanya merespons perubahan entity. Update pada entity mode Datastore yang tidak mengubah data (penulisan tanpa pengoperasian), tidak menghasilkan peristiwa penulisan atau update. Anda tidak dapat membuat peristiwa untuk properti tertentu saja.

Sertakan konteks autentikasi dalam peristiwa

Untuk menyertakan informasi autentikasi tambahan tentang peristiwa, gunakan pemicu peristiwa dengan ekstensi withAuthContext. Ekstensi ini menambahkan informasi tambahan tentang akun utama yang memicu peristiwa. Metode ini menambahkan atribut authtype dan authid, selain informasi yang ditampilkan dalam peristiwa dasar. Lihat referensi authcontext untuk mengetahui informasi selengkapnya tentang nilai atribut.

Menulis fungsi yang dipicu entity

Untuk menulis fungsi yang merespons Firestore dalam peristiwa mode Datastore, siapkan untuk menentukan hal berikut selama deployment:

jenis peristiwa pemicu
filter peristiwa pemicu untuk memilih entitas yang terkait dengan fungsi
kode fungsi untuk menjalankan

Filter peristiwa pemicu

Saat menentukan filter peristiwa, Anda dapat menentukan pencocokan entity yang persis atau pola jalur. Gunakan pola jalur untuk mencocokkan beberapa entity dengan karakter pengganti * atau **.

Misalnya, Anda dapat menentukan pencocokan entity yang sama persis untuk merespons perubahan pada entity berikut:

users/marie

Gunakan karakter pengganti, * atau **, untuk merespons perubahan dalam entity yang cocok dengan pola. Karakter pengganti * cocok dengan satu segmen, dan karakter pengganti multi-segmen ** cocok dengan nol atau beberapa segmen dalam pola.

Untuk pencocokan segmen tunggal (*), Anda juga dapat menggunakan grup tangkapan bernama, seperti users/{userId}.

Tabel berikut menunjukkan pola jalur yang valid:

Pola	Deskripsi
`users/*` atau `users/{userId}`	Cocok dengan semua entitas jenis `users`. Tidak cocok dengan level entitas turunan seperti `/users/marie/messages/33e2IxYBD9enzS50SJ68`
`users/**`	Mencocokkan semua entity jenis `users` dan semua entity turunan seperti `/users/marie/messages/33e2IxYBD9enzS50SJ68`

Untuk mempelajari pola jalur lebih lanjut, lihat Pola jalur Eventarc.

Pemicu Anda harus selalu menunjuk ke suatu entity, meskipun Anda menggunakan karakter pengganti. Lihat contoh berikut:

users/{userId=*}/{messages=*} tidak valid karena {messages=*} adalah ID jenis.
users/{userId=*}/{messages}/{messageId=*} valid karena {messageId=*} selalu mengarah ke entitas.

Pelarian karakter

Bagian ini menjelaskan situasi yang mengharuskan Anda meng-escape karakter dalam ID jenis dan ID entity. Dengan meng-escape karakter, filter peristiwa dapat menafsirkan ID dengan benar.

Jika ID jenis atau ID entity menyertakan karakter ~ atau /, Anda harus meng-escape ID dalam filter peristiwa. Untuk meng-escape ID, gunakan format __escENCODED_ID__. Ganti ENCODED_ID dengan ID jenis atau ID entity yang memiliki semua karakter ~ dan / yang diganti dengan ID encoding-nya, yaitu sebagai berikut:
- ~: ~0
- /: ~1
Misalnya, ID jenis user/profile menjadi __escusers~1profile__. Contoh pola jalur dengan ID jenis ini adalah __escusers~1profile__/{userId}
Jika menggunakan ID jenis atau ID entity . atau .. dalam filter peristiwa, Anda harus meng-escape ID sebagai berikut:
- .: __esc~2__
- ..: __esc~2~2__
Anda perlu meng-escape karakter . hanya jika ID-nya adalah . atau ... Misalnya, ID jenis customers.info tidak memerlukan escaping.
Jika ID jenis atau entity Anda adalah nilai numerik, bukan nilai string, Anda harus meng-escape ID dengan __idNUMERIC_VALUE__. Misalnya, pola jalur untuk entity jenis 111 dan ID entity 222 adalah __id111__/__id222__.
Jika Anda bermigrasi dari Cloud Datastore Lama ke Firestore dalam mode Datastore, database Anda mungkin berisi ID lama dalam encoding non-UTF8. Anda harus meng-escape ID ini dengan __bytesBASE64_ENCODING__. Ganti BASE64_ENCODING dengan encoding base-64 ID. Misalnya, pola jalur Task/{task} dengan escaping untuk ID jenis non-UTF8 Task menjadi __bytesVGFzaw==__/{task}.

Contoh fungsi

Contoh berikut menunjukkan cara menerima peristiwa mode Datastore. Untuk menggunakan data yang terlibat dalam suatu peristiwa, lihat kolom value dan old_value.

value: Objek EntityResult yang berisi snapshot entity pasca-operasi. Kolom ini tidak diisi untuk peristiwa penghapusan.
old_value: Objek EntityResult yang berisi snapshot entity pra-operasi. Kolom ini hanya diisi untuk peristiwa pembaruan dan penghapusan.

Java

Untuk mempelajari cara menginstal dan menggunakan library klien untuk mode Datastore, lihat Library klien mode Datastore. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Java mode Datastore.

Untuk melakukan autentikasi ke mode Datastore, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

import com.google.cloud.functions.CloudEventsFunction;
import com.google.events.cloud.datastore.v1.EntityEventData;
import com.google.protobuf.InvalidProtocolBufferException;
import io.cloudevents.CloudEvent;
import java.util.logging.Logger;

public class Datastore implements CloudEventsFunction {
  private static final Logger logger = Logger.getLogger(Datastore.class.getName());

  @Override
  public void accept(CloudEvent event) throws InvalidProtocolBufferException {
    EntityEventData datastoreEventData = EntityEventData.parseFrom(event.getData().toBytes());

    logger.info("Function triggered by event on: " + event.getSource());
    logger.info("Event type: " + event.getType());

    logger.info("Old value:");
    logger.info(datastoreEventData.getOldValue().toString());

    logger.info("New value:");
    logger.info(datastoreEventData.getValue().toString());
  }
}

Menyertakan dependensi proto di sumber Anda

Anda harus menyertakan file mode Datastore data.proto di direktori sumber untuk fungsi Anda. File ini mengimpor proto berikut yang juga harus Anda sertakan dalam direktori sumber:

Gunakan struktur direktori yang sama untuk dependensi. Misalnya, tempatkan struct.proto dalam google/protobuf.

File ini diperlukan untuk mendekode data peristiwa. Jika sumber fungsi Anda tidak menyertakan file ini, sumber fungsi akan menampilkan error saat dijalankan.

Atribut peristiwa

Setiap peristiwa menyertakan atribut data yang menyertakan informasi tentang peristiwa, seperti waktu peristiwa dipicu. Firestore dalam mode Datastore menambahkan data tambahan tentang database dan entity yang terlibat dalam peristiwa. Anda dapat mengakses atribut ini sebagai berikut:

Java

logger.info("Event time " + event.getTime());
logger.info("Event project: " + event.getExtension("project"));
logger.info("Event location: " + event.getExtension("location"));
logger.info("Database name: " + event.getExtension("database"));
logger.info("Database namespace: " + event.getExtension("namespace"));
logger.info("Database entity: " + event.getExtension("entity"));
// For withAuthContext events
logger.info("Auth information: " + event.getExtension("authid"));
logger.info("Auth information: " + event.getExtension("authtype"));

Men-deploy fungsi

Pengguna yang men-deploy Cloud Functions harus memiliki peran IAM Developer Cloud Functions atau peran yang mencakup izin yang sama. Lihat juga Konfigurasi tambahan untuk deployment.

Anda dapat men-deploy fungsi menggunakan gcloud CLI atau Konsol Google Cloud. Contoh di bawah ini menunjukkan deployment dengan gcloud CLI. Untuk mengetahui detail tentang deployment dengan Konsol Google Cloud, lihat Men-deploy Cloud Functions.

Di konsol Google Cloud, aktifkan Cloud Shell.

Aktifkan Cloud Shell

Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.
Gunakan perintah gcloud functions deploy untuk men-deploy fungsi:
```
gcloud functions deploy FUNCTION_NAME \
--gen2 \
--region=FUNCTION_LOCATION \
--trigger-location=TRIGGER_LOCATION \
--runtime=RUNTIME \
--source=SOURCE_LOCATION \
--entry-point=CODE_ENTRYPOINT \
--trigger-event-filters="type=EVENT_FILTER_TYPE" \
--trigger-event-filters="database=DATABASE" \
--trigger-event-filters="namespace=NAMESPACE" \
--trigger-event-filters-path-pattern="entity=ENTITY_OR_PATH" \
```
Argumen pertama, FUNCTION_NAME, adalah nama untuk fungsi yang di-deploy. Nama fungsi harus dimulai dengan huruf yang diikuti dengan maksimal 62 huruf, angka, tanda hubung, atau garis bawah, dan harus diakhiri dengan huruf atau angka. Ganti FUNCTION_NAME dengan nama fungsi yang valid. Kemudian, tambahkan flag berikut:
- Flag --gen2 menentukan bahwa Anda ingin men-deploy ke Cloud Functions (generasi ke-2). Jika flag ini tidak ada, deployment ke Cloud Functions (generasi ke-1) akan terjadi.
- Flag --region=FUNCTION_LOCATION menentukan region tempat men-deploy fungsi Anda.
  
  Untuk memaksimalkan kedekatan, tetapkan FUNCTION_LOCATION ke region yang dekat dengan database Firestore Anda. Jika database Firestore Anda berada di lokasi multi-region, tetapkan nilai ke us-central1 untuk database di nam5 dan ke europe-west4 untuk database di eur3. Untuk lokasi Firestore regional, tetapkan ke region yang sama.
- Flag --trigger-location=TRIGGER_LOCATION menentukan lokasi pemicu. Anda harus menetapkan TRIGGER_LOCATION ke lokasi database mode Datastore Anda.
- Flag --runtime=RUNTIME menentukan runtime bahasa yang digunakan fungsi Anda. Cloud Functions mendukung beberapa runtime. Lihat Waktu proses untuk informasi selengkapnya. Setel RUNTIME ke runtime yang didukung.
- Flag --source=SOURCE_LOCATION menentukan lokasi kode sumber fungsi Anda. Lihat informasi berikut untuk mengetahui detailnya:
  Setel SOURCE_LOCATION ke lokasi kode sumber fungsi Anda.
- Flag --entry-point=CODE_ENTRYPOINT menentukan titik masuk ke fungsi Anda dalam kode sumber. Ini adalah kode yang dijalankan oleh fungsi Anda saat dijalankan. Anda harus menetapkan CODE_ENTRYPOINT ke nama fungsi atau nama class yang sepenuhnya memenuhi syarat dan ada dalam kode sumber. Lihat Titik entri fungsi untuk informasi selengkapnya.
- Flag --trigger-event-filters menentukan filter peristiwa yang menyertakan jenis pemicu dan entity atau jalur yang memicu peristiwa. Tetapkan nilai atribut berikut untuk menentukan filter peristiwa Anda:
  - type=EVENT_FILTER_TYPE: Firestore mendukung jenis peristiwa berikut:
    - google.cloud.datastore.entity.v1.created: peristiwa dikirim saat entity ditulis untuk pertama kalinya.
    - google.cloud.datastore.entity.v1.updated: peristiwa dikirim saat entity sudah ada dan memiliki nilai yang berubah.
    - google.cloud.datastore.entity.v1.deleted: peristiwa dikirim saat entity dihapus.
    - google.cloud.datastore.entity.v1.written: peristiwa dikirim saat entitas dibuat, diperbarui, atau dihapus.
    - google.cloud.datastore.entity.v1.created.withAuthContext: peristiwa dikirim saat dokumen ditulisi untuk pertama kalinya dan peristiwa menyertakan informasi autentikasi tambahan
    - google.cloud.datastore.entity.v1.updated.withAuthContext: peristiwa dikirim saat dokumen sudah ada dan nilainya berubah. Menyertakan informasi autentikasi tambahan
    - google.cloud.datastore.entity.v1.deleted.withAuthContext: peristiwa dikirim saat dokumen dihapus. Menyertakan informasi autentikasi tambahan
    - google.cloud.datastore.entity.v1.written.withAuthContext: peristiwa dikirim saat dokumen dibuat, diperbarui, atau dihapus dan peristiwa. Menyertakan informasi autentikasi tambahan
    Tetapkan EVENT_FILTER_TYPE ke salah satu jenis peristiwa ini.
  - database=DATABASE: database Firestore. Untuk nama database default, tetapkan DATABASE ke (default).
  - namespace=NAMESPACE: namespace database. Untuk nama database default, tetapkan NAMESPACE ke (default). Hapus flag tersebut agar sesuai dengan namespace apa pun.
    
    Catatan: Tetapkan tepat ke (default) untuk namespace default. Ini adalah nama resource non-kanonis yang hanya digunakan untuk Eventarc. Jangan tetapkan ke [default] seperti yang ditunjukkan di Konsol Google Cloud.
  - entity=ENTITY_OR_PATH: jalur database yang memicu peristiwa saat data dibuat, diperbarui, atau dihapus. Nilai yang diterima untuk ENTITY_OR_PATH adalah:
    - Sama; misalnya, --trigger-event-filters="entity='users/marie'"
    - Pola jalur; misalnya, --trigger-event-filters-path-pattern="entity='users/*'". Untuk mengetahui informasi selengkapnya, lihat Memahami pola jalur.
  Secara opsional, Anda dapat menentukan opsi konfigurasi, jaringan, dan keamanan tambahan saat men-deploy fungsi.
  
  Untuk referensi lengkap tentang perintah deployment dan flag-nya, lihat dokumentasi gcloud functions deploy.

Contoh deployment

Contoh berikut menunjukkan deployment dengan Google Cloud CLI.

Deploy fungsi untuk database di region us-west2:

gcloud functions deploy gcfv2-trigger-datastore-node \
--gen2 \
--region=us-west2 \
--trigger-location=us-west2 \
--runtime=nodejs18 \
--source=gs://example_bucket-1/datastoreEventFunction.zip \
--entry-point=makeUpperCase \
--trigger-event-filters=type=google.cloud.datastore.entity.v1.written \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern="entity='messages/{pushId}'"

Deploy fungsi untuk database di multi-region nam5:

gcloud functions deploy gcfv2-trigger-datastore-python \
--gen2 \
--region=us-central1 \
--trigger-location=nam5 \
--runtime=python311 \
--source=gs://example_bucket-1/datastoreEventFunction.zip \
--entry-point=make_upper_case \
--trigger-event-filters=type=google.cloud.datastore.entity.v1.written.withAuthContext \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern="entity='messages/{pushId}'"

Batasan

Perhatikan batasan berikut untuk pemicu Firestore untuk Cloud Functions:

Pengurutan tidak dijamin. Perubahan cepat dapat memicu pemanggilan fungsi dalam urutan yang tidak terduga.
Peristiwa dikirim setidaknya satu kali, tetapi satu peristiwa dapat menghasilkan beberapa pemanggilan fungsi. Hindari mengandalkan mekanisme tepat satu kali, dan tulis fungsi idempoten.
Firestore dalam mode Datastore memerlukan Cloud Functions (generasi ke-2). Cloud Functions (generasi ke-1) tidak mendukung mode Datastore.
Cloud Functions (generasi ke-1) hanya berfungsi dengan database "(default)" dan tidak mendukung database bernama Firestore. Gunakan Cloud Functions (generasi ke-2) untuk mengonfigurasi peristiwa untuk database bernama.
Pemicu dikaitkan dengan satu database. Anda tidak dapat membuat pemicu yang cocok dengan beberapa database.
Menghapus database tidak secara otomatis menghapus pemicu untuk database tersebut. Pemicu berhenti mengirim peristiwa, tetapi akan tetap ada sampai Anda menghapus pemicu.
Jika peristiwa yang cocok melebihi ukuran permintaan maksimum, peristiwa tersebut mungkin tidak akan dikirim ke Cloud Functions (generasi ke-1).
- Peristiwa yang tidak terkirim karena ukuran permintaan akan dicatat ke dalam log dalam log platform dan akan diperhitungkan dalam penggunaan log untuk project.
- Anda dapat menemukan log ini di Logs Explorer dengan pesan "Event dapat mengirim ke Cloud function karena ukuran melebihi batas untuk generasi ke-1..." dengan tingkat keparahan error. Anda dapat menemukan nama fungsi di bawah kolom functionName. Jika kolom receiveTimestamp masih berada dalam waktu satu jam dari sekarang, Anda dapat menyimpulkan konten peristiwa yang sebenarnya dengan membaca dokumen yang dimaksud menggunakan snapshot sebelum dan setelah stempel waktu.
- Untuk menghindari peristiwa seperti ini, Anda dapat:
  - Melakukan migrasi dan upgrade ke Cloud Functions (generasi ke-2)
  - Memperkecil dokumen
  - Menghapus Cloud Functions yang dimaksud
- Anda dapat menonaktifkan logging itu sendiri menggunakan pengecualian, tetapi perhatikan bahwa peristiwa yang melanggar tetap tidak akan dikirim.

Eventarc dan Firestore dalam lokasi mode Datastore

Eventarc tidak mendukung multi-region untuk pemicu peristiwa Firestore, tetapi Anda masih dapat membuat pemicu untuk database Firestore di lokasi multi-region. Eventarc memetakan lokasi multi-region Firestore ke region Eventarc berikut:

Firestore multi-region	Wilayah Eventarc
`nam5`	`us-central1`
`eur3`	`europe-west4`

Langkah selanjutnya

Pelajari arsitektur berbasis peristiwa.
Lihat contoh kode untuk mode Datastore.