Menggunakan kembali kode Cloud Functions sebagai Ekstensi Firebase

1. Sebelum memulai

Firebase Extensions menjalankan tugas atau serangkaian tugas tertentu sebagai respons terhadap permintaan HTTP atau peristiwa pemicu dari produk Firebase dan Google lainnya seperti Firebase Cloud Messaging, Cloud Firestore, atau Pub/Sub.

Hal yang akan Anda build

Dalam codelab ini, Anda akan membuat ekstensi Firebase untuk geohashing. Setelah di-deploy, ekstensi Anda akan mengonversi koordinat X dan Y menjadi geohash sebagai respons terhadap peristiwa Firestore atau melalui pemanggilan fungsi yang dapat dipanggil. Cara ini dapat digunakan sebagai alternatif untuk menerapkan pustaka geofire di semua platform target Anda untuk menyimpan data, sehingga menghemat waktu Anda.

Ekstensi geohash yang ditampilkan di Firebase console

Hal yang akan Anda pelajari

  • Cara mengambil kode Cloud Functions yang ada dan mengubahnya menjadi Ekstensi Firebase yang dapat didistribusikan
  • Cara menyiapkan file extension.yaml
  • Cara menyimpan string sensitif (kunci API) di ekstensi
  • Cara mengizinkan developer ekstensi mengonfigurasinya agar sesuai dengan kebutuhan mereka
  • Cara menguji dan men-deploy ekstensi

Hal yang akan Anda perlukan

  • Firebase CLI (instal dan login)
  • Akun Google, seperti akun Gmail
  • Node.js dan npm
  • Lingkungan pengembangan favorit Anda

2. Memulai persiapan

Mendapatkan kode

Semua yang Anda perlukan untuk ekstensi ini ada di repositori GitHub. Untuk memulai, ambil kode dan buka di lingkungan pengembangan favorit Anda.

  1. Mengekstrak file zip yang didownload.
  2. Untuk menginstal dependensi yang diperlukan, buka terminal di direktori functions dan jalankan perintah npm install.

Menyiapkan Firebase

Codelab ini sangat menganjurkan penggunaan emulator Firebase. Jika Anda ingin mencoba pengembangan ekstensi dengan project Firebase sungguhan, lihat membuat project Firebase. Codelab ini menggunakan Cloud Functions, jadi jika Anda menggunakan project Firebase sungguhan, bukan emulator, Anda harus mengupgrade ke paket harga Blaze.

Ingin melompat ke depan?

Anda dapat mendownload versi codelab yang sudah selesai. Jika Anda mengalami masalah di sepanjang proses atau ingin melihat tampilan ekstensi yang sudah selesai, lihat cabang codelab-end di repositori GitHub atau download zip yang sudah selesai.

3. Meninjau kode

  • Buka file index.ts dari file zip. Perhatikan bahwa file ini berisi dua deklarasi Cloud Functions di dalamnya.

Apa fungsi ini?

Fungsi demo ini digunakan untuk geohashing. Fungsi ini mengambil pasangan koordinat dan mengubahnya menjadi format yang dioptimalkan untuk kueri geo di Firestore. Fungsi ini menyimulasikan penggunaan panggilan API sehingga Anda dapat mempelajari lebih lanjut cara menangani jenis data sensitif dalam ekstensi. Untuk mengetahui informasi selengkapnya, lihat dokumentasi tentang menjalankan kueri Geo pada data di Firestore.

Konstanta fungsi

Konstanta dideklarasikan di awal, di bagian atas file index.ts. Beberapa konstanta ini dirujuk dalam pemicu yang ditentukan ekstensi.

index.ts

import {firestore} from "firebase-functions";
import {initializeApp} from "firebase-admin/app";
import {GeoHashService, ResultStatusCode} from "./fake-geohash-service";
import {onCall} from "firebase-functions/v1/https";
import {fieldValueExists} from "./utils";

const documentPath = "users/{uid}";
const xField = "xv";
const yField = "yv";
const apiKey = "1234567890";
const outputField = "hash";

initializeApp();

const service = new GeoHashService(apiKey);

Pemicu Firestore

Fungsi pertama dalam file index.ts akan terlihat seperti ini:

index.ts

export const locationUpdate = firestore.document(documentPath)
  .onWrite((change) => {
    // item deleted
    if (change.after == null) {
      return 0;
    }
    // double check that both values exist for computation
    if (
      !fieldValueExists(change.after.data(), xField) ||
      !fieldValueExists(change.after.data(), yField)
    ) {
      return 0;
    }
    const x: number = change.after.data()![xField];
    const y: number = change.after.data()![yField];
    const hash = service.convertToHash(x, y);
    // This is to check whether the hash value has changed. If
    // it hasn't, you don't want to write to the document again as it
    // would create a recursive write loop.
    if (fieldValueExists(change.after.data(), outputField)
      && change.after.data()![outputField] == hash) {
      return 0;
    }
    return change.after.ref
      .update(
        {
          [outputField]: hash.hash,
        }
      );
  });

Fungsi ini adalah pemicu Firestore. Saat peristiwa tulis terjadi di database, fungsi bereaksi terhadap peristiwa tersebut dengan menelusuri kolom xv dan kolom yv, dan, jika kedua kolom tersebut ada, fungsi akan menghitung geohash dan menulis output ke lokasi output dokumen yang ditentukan. Dokumen input ditentukan oleh konstanta users/{uid}, yang berarti bahwa fungsi membaca setiap dokumen yang ditulis ke koleksi users/, lalu memproses geohash untuk dokumen tersebut. Kemudian, hash akan ditampilkan ke kolom hash dalam dokumen yang sama.

Fungsi Callable

Fungsi berikutnya dalam file index.ts akan terlihat seperti ini:

index.ts

export const callableHash = onCall((data, context) => {
  if (context.auth == undefined) {
    return {error: "Only authorized users are allowed to call this endpoint"};
  }
  const x = data[xField];
  const y = data[yField];
  if (x == undefined || y == undefined) {
    return {error: "Either x or y parameter was not declared"};
  }
  const result = service.convertToHash(x, y);
  if (result.status != ResultStatusCode.ok) {
    return {error: `Something went wrong ${result.message}`};
  }
  return {result: result.hash};
});

Perhatikan fungsi onCall. Hal ini menunjukkan bahwa fungsi ini adalah fungsi yang dapat dipanggil, yang dapat dipanggil dari dalam kode aplikasi klien Anda. Fungsi yang dapat dipanggil ini menggunakan parameter x dan y serta menampilkan geohash. Meskipun fungsi ini tidak akan dipanggil secara langsung dalam codelab ini, fungsi ini disertakan di sini sebagai contoh sesuatu yang perlu dikonfigurasi di ekstensi Firebase.

4. Siapkan file ekstensi.yaml

Setelah mengetahui fungsi kode Cloud Functions dalam ekstensi Anda, Anda siap mengemasnya untuk didistribusikan. Setiap Firebase Extension dilengkapi dengan file extension.yaml yang menjelaskan fungsi dan perilaku ekstensi.

File extension.yaml memerlukan beberapa metadata awal tentang ekstensi Anda. Setiap langkah berikut membantu Anda memahami arti semua kolom dan alasan Anda memerlukannya.

  1. Buat file extension.yaml di direktori utama project yang Anda download sebelumnya. Mulai dengan menambahkan berikut ini:
name: geohash-ext
version: 0.0.1
specVersion: v1beta  # Firebase Extensions specification version (do not edit)

Nama ekstensi digunakan sebagai dasar ID instance ekstensi (pengguna dapat menginstal beberapa instance ekstensi, yang masing-masing memiliki ID sendiri). Kemudian, Firebase membuat nama akun layanan ekstensi dan resource khusus ekstensi menggunakan ID instance tersebut. Nomor versi menunjukkan versi ekstensi Anda. Versi ini harus mengikuti pembuatan versi semantik, dan Anda perlu memperbaruinya setiap kali Anda membuat perubahan pada fungsi ekstensi. Versi spesifikasi ekstensi digunakan untuk menentukan spesifikasi ekstensi Firebase yang akan diikuti, dalam hal ini, v1beta digunakan.

  1. Tambahkan beberapa detail yang mudah dipahami ke file YAML:
...

displayName: Latitude and longitude to GeoHash converter
description: A converter for changing your Latitude and longitude coordinates to geohashes.

Nama tampilan adalah representasi nama ekstensi Anda yang mudah dipahami saat developer berinteraksi dengan ekstensi Anda. Deskripsi memberikan ringkasan singkat tentang fungsi ekstensi. Saat di-deploy di extensions.dev, ekstensi akan terlihat seperti ini:

Ekstensi Geohash Converter seperti yang terlihat di extensions.dev

  1. Tentukan lisensi untuk kode di ekstensi Anda.
...

license: Apache-2.0  # The license you want for the extension
  1. Tunjukkan siapa yang menulis ekstensi dan apakah penagihan diperlukan untuk menginstalnya:
...

author:
  authorName: AUTHOR_NAME
  url: https://github.com/Firebase

billingRequired: true

Bagian author digunakan untuk memberi tahu pengguna siapa yang harus dihubungi jika mereka mengalami masalah dengan ekstensi atau ingin mengetahui informasi lebih lanjut tentang ekstensi tersebut. billingRequired adalah parameter wajib dan harus disetel ke true karena semua ekstensi mengandalkan Cloud Functions, yang memerlukan paket Blaze.

Hal ini mencakup jumlah minimum kolom yang diperlukan dalam file extension.yaml untuk mengidentifikasi ekstensi ini. Untuk mengetahui detail selengkapnya tentang informasi identifikasi lain yang dapat Anda tentukan dalam ekstensi, lihat dokumentasi.

5. Konversi kode Cloud Functions menjadi resource Ekstensi

Resource ekstensi adalah item yang dibuat Firebase di project selama penginstalan ekstensi. Ekstensi kemudian memiliki resource tersebut dan memiliki akun layanan tertentu yang beroperasi di dalamnya. Dalam project ini, resource tersebut adalah Cloud Functions, yang harus ditentukan dalam file extension.yaml karena ekstensi tidak akan otomatis membuat resource dari kode di folder fungsi. Jika Cloud Functions Anda tidak dideklarasikan secara eksplisit sebagai resource, Cloud Functions tersebut tidak dapat di-deploy saat ekstensi di-deploy.

Lokasi deployment yang ditentukan pengguna

  1. Izinkan pengguna menentukan lokasi tempat mereka ingin men-deploy ekstensi ini dan memutuskan apakah lebih baik menghosting ekstensi lebih dekat dengan pengguna akhir atau lebih dekat dengan database mereka. Dalam file extension.yaml, sertakan opsi untuk memilih lokasi.

extension.yaml

Sekarang Anda siap menulis konfigurasi untuk resource fungsi.

  1. Di file extension.yaml, buat objek resource untuk fungsi locationUpdate. Tambahkan kode berikut ke file extension.yaml:
resources:
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/users/{uid}

Anda menentukan name sebagai nama fungsi yang ditentukan dalam file index.ts project. Anda menentukan type fungsi yang di-deploy, yang untuk saat ini harus selalu berupa firebaseextensions.v1beta.function. Kemudian, Anda menentukan properties fungsi ini. Properti pertama yang Anda tentukan adalah eventTrigger yang terkait dengan fungsi ini. Untuk mencerminkan apa yang saat ini didukung ekstensi, Anda menggunakan eventType dari providers/cloud.firestore/eventTypes/document.write, yang dapat ditemukan dalam dokumentasi Menulis Cloud Functions untuk ekstensi Anda. Anda menentukan resource sebagai lokasi dokumen. Karena tujuan Anda saat ini adalah mencerminkan apa yang ada dalam kode, jalur dokumen memproses users/{uid}, dengan lokasi database default yang mendahuluinya.

  1. Ekstensi memerlukan izin baca dan tulis untuk database Firestore. Di bagian paling akhir file extension.yaml, tentukan peran IAM yang harus diakses ekstensi agar dapat menggunakan database di project Firebase developer.
roles:
  - role: datastore.user
    reason: Allows the extension to read / write to your Firestore instance.

Peran datastore.user berasal dari daftar peran IAM yang didukung untuk ekstensi. Karena ekstensi akan membaca dan menulis, peran datastore.user sangat cocok di sini.

  1. Fungsi yang dapat dipanggil juga harus ditambahkan. Di file extension.yaml, buat resource baru di bawah properti resource. Properti ini khusus untuk fungsi yang dapat dipanggil:
  - name: callableHash
    type: firebaseextensions.v1beta.function
    properties:
      httpsTrigger: {}

Meskipun resource sebelumnya menggunakan eventTrigger, di sini Anda menggunakan httpsTrigger, yang mencakup fungsi callable dan fungsi HTTPS.

Pemeriksaan kode

Ada banyak konfigurasi yang harus dilakukan agar extension.yaml Anda cocok dengan semua yang dilakukan oleh kode dalam file index.ts. Berikut tampilan file extension.yaml yang sudah selesai saat ini:

extension.yaml

name: geohash-ext
version: 0.0.1
specVersion: v1beta  # Firebase Extensions specification version (do not edit)

displayName: Latitude and Longitude to GeoHash converter
description: A converter for changing your Latitude and Longitude coordinates to geohashes.

license: Apache-2.0  # The license you want for the extension

author:
  authorName: Sparky
  url: https://github.com/Firebase

billingRequired: true

resources:
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/users/{uid}
  - name: callableHash
    type: firebaseextensions.v1beta.function
    properties:
      httpsTrigger: {}

roles:
  - role: datastore.user
    reason: Allows the extension to read / write to your Firestore instance.

Pemeriksaan status

Pada tahap ini, Anda telah menyiapkan bagian fungsional awal ekstensi, sehingga Anda dapat mencobanya menggunakan emulator Firebase.

  1. Jika belum, panggil npm run build di folder fungsi project ekstensi yang didownload.
  2. Buat direktori baru di sistem host Anda dan hubungkan direktori tersebut ke project Firebase Anda menggunakan firebase init.
cd ..
mkdir sample-proj
cd sample-proj
firebase init --project=projectID-or-alias

    This command creates a `firebase.json` file in the directory. In the following steps, you push the configuration specified in this file to Firebase.
  1. Dari direktori yang sama, jalankan firebase ext:install. Ganti /path/to/extension dengan jalur absolut ke direktori yang berisi file extension.yaml Anda.
firebase ext:install /path/to/extension

    This command does two things:
  • Langkah ini akan meminta Anda untuk menentukan konfigurasi instance ekstensi, dan membuat file *.env yang berisi informasi konfigurasi untuk instance tersebut.
  • Tindakan ini akan menambahkan instance ekstensi ke bagian extensions pada firebase.json Anda. Bagian ini berfungsi sebagai peta ID instance ke versi ekstensi.
  • Karena Anda men-deploy project secara lokal, Anda dapat menentukan bahwa Anda ingin menggunakan file lokal, bukan Google Cloud Secret Manager.

Screenshot proses penginstalan ekstensi yang menunjukkan bahwa File lokal digunakan untuk secret saat menginstal ekstensi ini

  1. Mulai emulator Firebase dengan konfigurasi baru:
firebase emulators:start
  1. Setelah menjalankan emulators:start, buka tab Firestore di webview emulator.
  2. Tambahkan dokumen ke koleksi users dengan kolom angka xv dan kolom angka yv.

Kotak dialog yang ditampilkan di Firebase Emulator untuk memulai pengumpulan dengan ID pengumpulan yang berisi frasa

  1. Jika Anda berhasil menginstal ekstensi, ekstensi akan membuat kolom baru bernama hash dalam dokumen.

Koleksi pengguna dengan dokumen pengguna yang memiliki kolom xv, yv, dan hash.

Pembersihan untuk menghindari konflik

  • Setelah selesai menguji, hapus instalasi ekstensi—Anda akan memperbarui kode ekstensi dan tidak ingin terjadi konflik dengan ekstensi saat ini nanti.

Ekstensi memungkinkan beberapa versi ekstensi yang sama diinstal sekaligus, jadi dengan meng-uninstal, Anda memastikan tidak ada konflik dengan ekstensi yang diinstal sebelumnya.

firebase ext:uninstall geohash-ext

Solusi saat ini berfungsi, tetapi seperti yang disebutkan di awal project, ada kunci API yang dikodekan secara permanen untuk menyimulasikan komunikasi dengan layanan. Bagaimana cara menggunakan kunci API pengguna akhir, bukan kunci API yang awalnya diberikan? Baca terus untuk mengetahuinya.

6. Membuat ekstensi yang dapat dikonfigurasi pengguna

Pada titik ini dalam codelab, Anda memiliki ekstensi yang dikonfigurasi untuk digunakan dengan penyiapan fungsi yang sudah Anda tulis, tetapi bagaimana jika pengguna ingin menggunakan lintang dan bujur, bukan y dan x untuk kolom yang menunjukkan lokasi pada bidang kartesius? Selain itu, bagaimana cara membuat pengguna akhir memberikan kunci API mereka sendiri, bukan membiarkan mereka menggunakan kunci API yang diberikan? Anda dapat dengan cepat melebihi kuota untuk API tersebut. Dalam hal ini, Anda menyiapkan dan menggunakan parameter.

Tentukan parameter dasar dalam file extension.yaml

Mulailah dengan mengonversi item yang berpotensi memiliki konfigurasi kustom bagi developer. Yang pertama adalah parameter XFIELD dan YFIELD.

  1. Di file extension.yaml, tambahkan kode berikut, yang menggunakan parameter kolom XFIELD dan YFIELD. Parameter ini berada di dalam properti YAML params yang ditentukan sebelumnya:

extension.yaml

params:
  - param: XFIELD
    label: The X Field Name
    description: >-
      The X Field is also known as the **longitude** value. What does
      your Firestore instance refer to as the X value or the longitude
      value. If no value is specified, the extension searches for
      field 'xv'.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    default: xv
    required: false
    immutable: false
    example: xv
  - param: YFIELD
    label: The Y Field Name
    description: >-
      The Y Field is also known as the **latitude** value. What does
      your Firestore instance refer to as the Y value or the latitude
      value. If no value is specified, the extension searches for
      field 'yv'.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    default: yv
    required: false
    immutable: false
    example: yv
  • param memberi nama parameter dengan cara yang dapat dilihat oleh Anda, produsen ekstensi. Gunakan nilai ini nanti saat menentukan nilai parameter.
  • label adalah ID yang dapat dibaca manusia untuk memberi tahu developer fungsi parameter tersebut.
  • description memberikan deskripsi mendetail tentang nilai. Karena mendukung markdown, kolom ini dapat ditautkan ke dokumentasi tambahan, atau dapat menandai kata-kata yang mungkin penting bagi developer.
  • type menentukan mekanisme input untuk cara pengguna menetapkan nilai parameter. Ada banyak jenis yang ada, termasuk string, select, multiSelect, selectResource, dan secret. Untuk mempelajari lebih lanjut setiap opsi ini, lihat dokumentasi.
  • validationRegex membatasi entri developer ke nilai regex tertentu (dalam contoh, ini didasarkan pada pedoman nama kolom sederhana yang dapat ditemukan di sini); dan jika gagal...
  • validationErrorMessage memberi tahu developer tentang nilai kegagalan.
  • default adalah nilai yang akan ada jika developer tidak memasukkan teks apa pun.
  • required berarti developer tidak perlu memasukkan teks apa pun.
  • immutable memungkinkan developer memperbarui ekstensi ini dan mengubah nilai ini. Dalam hal ini, developer harus dapat mengubah nama kolom seiring perubahan persyaratannya.
  • example memberikan gambaran tentang seperti apa input yang valid.

Banyak sekali yang harus dipahami.

  1. Anda memiliki tiga parameter lagi yang harus ditambahkan ke file extension.yaml sebelum menambahkan parameter khusus.
  - param: INPUTPATH
    label: The input document to listen to for changes
    description: >-
      This is the document where you write an x and y value to. Once
      that document has received a value, it notifies the extension to
      calculate a geohash and store that in an output document in a certain
      field. This accepts function [wildcard parameters](https://firebase.google.com/docs/functions/firestore-events#wildcards-parameters)
    type: string
    validationRegex: ^[^/]+(/[^/]*/[^/]*)*/[^/]+$
    validationErrorMessage: >-
      This must point to a document path, not a collection path from the root
      of the database. It must also not start or end with a '/' character.
    required: true
    immutable: false
    example: users/{uid}
  - param: OUTPUTFIELD
    label: Geohash field
    description: >-
      This specifies the field in the output document to store the geohash in.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    required: false
    default: hash
    immutable: false
    example: hash

Menentukan parameter sensitif

Sekarang, Anda perlu mengelola kunci API yang ditentukan pengguna. Ini adalah string sensitif yang tidak boleh disimpan dalam teks biasa dalam fungsi. Sebagai gantinya, simpan nilai ini di Cloud Secret Manager. Ini adalah lokasi khusus di cloud yang menyimpan secret terenkripsi, dan mencegahnya bocor secara tidak sengaja. Hal ini mengharuskan developer membayar penggunaan layanan ini, tetapi menambahkan lapisan keamanan ekstra pada kunci API mereka dan berpotensi membatasi aktivitas penipuan. Dokumentasi pengguna memberi tahu developer bahwa ini adalah layanan berbayar, sehingga tidak ada kejutan dalam penagihan. Secara keseluruhan, penggunaannya mirip dengan resource string lainnya yang disebutkan di atas. Satu-satunya perbedaan adalah jenis yang disebut secret.

  • Di file extension.yaml, tambahkan kode berikut:

extension.yaml

  - param: APIKEY
    label: GeohashService API Key
    description: >-
      Your geohash service API Key. Since this is a demo, and not a real
      service, you can use : 1234567890.
    type: secret
    required: true
    immutable: false

Perbarui resource atribut untuk menggunakan parameter

Seperti yang disebutkan sebelumnya, resource (bukan fungsi) menentukan cara resource diamati, sehingga resource locationUpdate perlu diupdate untuk menggunakan parameter baru.

  • Di file extension.yaml, tambahkan kode berikut:

extension.yaml

## Change from this
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/users/{uid}]

## To this
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/${INPUTPATH}

Periksa file extension.yaml

  • Tinjau file extension.yaml. Ini akan terlihat seperti berikut:

extension.yaml

name: geohash-ext
version: 0.0.1
specVersion: v1beta  # Firebase Extensions specification version (do not edit)

displayName: Latitude and Longitude to GeoHash converter
description: A converter for changing your Latitude and Longitude coordinates to geohashes.

license: Apache-2.0  # The license you want to use for the extension

author:
  authorName: Sparky
  url: https://github.com/Firebase

billingRequired: true

params:
  - param: XFIELD
    label: The X Field Name
    description: >-
      The X Field is also known as the **longitude** value. What does
      your Firestore instance refer to as the X value or the longitude
      value. If you don't provide a value for this field, the extension will use 'xv' as the default value.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    default: xv
    required: false
    immutable: false
    example: xv
  - param: YFIELD
    label: The Y Field Name
    description: >-
      The Y Field is also known as the **latitude** value. What does
      your Firestore instance refer to as the Y value or the latitude
      Value. If you don't provide a value for this field, the extension will use 'yv' as the default value.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    default: yv
    required: false
    immutable: false
    example: yv
  - param: INPUTPATH
    label: The input document to listen to for changes
    description: >-
      This is the document where you write an x and y value to. Once
      that document has been modified, it notifies the extension to
      compute a geohash and store that in an output document in a certain
      field. This accepts function [wildcard parameters](https://firebase.google.com/docs/functions/firestore-events#wildcards-parameters)
    type: string
    validationRegex: ^[^/]+(/[^/]*/[^/]*)*/[^/]+$
    validationErrorMessage: >-
      This must point to a document path, not a collection path from the root
      of the database. It must also not start or end with a '/' character.
    required: true
    immutable: false
    example: users/{uid}
  - param: OUTPUTFIELD
    label: Geohash field
    description: >-
      This specifies the field in the output document to store the geohash in.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    required: false
    default: hash
    immutable: false
    example: hash
  - param: APIKEY
    label: GeohashService API Key
    description: >-
      Your geohash service API Key. Since this is a demo, and not a real
      service, you can use : 1234567890.
    type: secret
    required: true
    immutable: false

resources:
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/${INPUTPATH}
  - name: callableHash
    type: firebaseextensions.v1beta.function
    properties:
      httpsTrigger: {}

roles:
  - role: datastore.user
    reason: Allows the extension to read / write to your Firestore instance.

Mengakses parameter dalam kode

Setelah semua parameter dikonfigurasi dalam file extension.yaml, tambahkan parameter tersebut ke file index.ts.

  • Dalam file index.ts, ganti nilai default dengan process.env.PARAMETER_NAME, yang mengambil nilai parameter yang sesuai dan mengisinya dalam kode fungsi yang di-deploy di project Firebase developer.

index.ts

// Replace this:
const documentPath = "users/{uid}";
const xField = "xv";
const yField = "yv";
const apiKey = "1234567890";
const outputField = "hash";

// with this:
const documentPath = process.env.INPUTPATH!; // this value is ignored since its read from the resource
const xField = process.env.XFIELD!;
const yField = process.env.YFIELD!;
const apiKey = process.env.APIKEY!;
const outputField = process.env.OUTPUTFIELD!;

Biasanya, Anda ingin melakukan pemeriksaan null dengan nilai variabel lingkungan, tetapi dalam hal ini, Anda yakin bahwa nilai parameter disalin dengan benar. Kode kini dikonfigurasi untuk berfungsi dengan parameter ekstensi.

7. Membuat dokumentasi pengguna

Sebelum menguji kode di emulator atau di marketplace ekstensi Firebase, ekstensi harus didokumentasikan agar developer mengetahui apa yang mereka dapatkan saat menggunakan ekstensi.

  1. Mulailah dengan membuat file PREINSTALL.md, yang digunakan untuk mendeskripsikan fungsi, prasyarat untuk penginstalan, dan potensi implikasi penagihan.

PREINSTALL.md

Use this extension to automatically convert documents with a latitude and
longitude to a geohash in your database. Additionally, this extension includes a callable function that allows users to make one-time calls
to convert an x,y coordinate into a geohash.

Geohashing is supported for latitudes between 90 and -90 and longitudes
between 180 and -180.

#### Third Party API Key

This extension uses a fictitious third-party API for calculating the
geohash. You need to supply your own API keys. (Since it's fictitious,
you can use 1234567890 as an API key).

#### Additional setup

Before installing this extension, make sure that you've [set up a Cloud
Firestore database](https://firebase.google.com/docs/firestore/quickstart) in your Firebase project.

After installing this extension, you'll need to:

- Update your client code to point to the callable geohash function if you
want to perform arbitrary geohashes.

Detailed information for these post-installation tasks are provided after
you install this extension.

#### Billing
To install an extension, your project must be on the [Blaze (pay as you
go) plan](https://firebase.google.com/pricing)

- This extension uses other Firebase and Google Cloud Platform services,
which have associated charges if you exceed the service's no-cost tier:
 - Cloud Firestore
 - Cloud Functions (Node.js 16+ runtime. [See
FAQs](https://firebase.google.com/support/faq#extensions-pricing))
 - [Cloud Secret Manager](https://cloud.google.com/secret-manager/pricing)
  1. Untuk menghemat waktu dalam menulis README.md untuk project ini, gunakan metode praktis:
firebase ext:info . --markdown > README.md

Tindakan ini menggabungkan konten file PREINSTALL.md dan detail tambahan tentang ekstensi Anda dari file extension.yaml.

Terakhir, beri tahu developer ekstensi tentang beberapa detail tambahan terkait ekstensi yang baru saja diinstal. Developer mungkin mendapatkan beberapa petunjuk dan informasi tambahan setelah menyelesaikan penginstalan dan mungkin mendapatkan beberapa tugas pasca-penginstalan yang terperinci seperti menyiapkan kode klien di sini.

  1. Buat file POSTINSTALL.md, lalu sertakan informasi pasca-penginstalan berikut:

POSTINSTALL.md

Congratulations on installing the geohash extension!

#### Function information

* **Firestore Trigger** - ${function:locationUpdate.name} was installed
and is invoked when both an x field (${param:XFIELD}) and y field
(${param:YFIELD}) contain a value.

* **Callable Trigger** - ${function:callableHash.name} was installed and
can be invoked by writing the following client code:
 ```javascript
import { getFunctions, httpsCallable } from "firebase/functions";
const functions = getFunctions();
const geoHash = httpsCallable(functions, '${function:callableHash.name}');
geoHash({ ${param:XFIELD}: -122.0840, ${param:YFIELD}: 37.4221 })
  .then((result) => {
    // Read result of the Cloud Function.
    /** @type {any} */
    const data = result.data;
    const error = data.error;
    if (error != null) {
        console.error(`callable error : ${error}`);
    }
    const result = data.result;
    console.log(result);
  });

Pemantauan

Sebagai praktik terbaik, Anda dapat memantau aktivitas ekstensi yang diinstal, termasuk memeriksa respons, penggunaan, dan log-nya.

The output rendering looks something like this when it's deployed:

<img src="img/82b54a5c6ca34b3c.png" alt="A preview of the latitude and longitude geohash converter extension in the firebase console"  width="957.00" />


## Test the extension with the full configuration
Duration: 03:00


It's time to make sure that the user-configurable extension is working the way it is intended.

* Change into the functions folder and ensure that the latest compiled version of the extensions exists. In the extensions project functions directory, call:

```console
npm run build

Tindakan ini akan mengompilasi ulang fungsi sehingga kode sumber terbaru siap di-deploy bersama ekstensi saat di-deploy ke emulator atau langsung ke Firebase.

Selanjutnya, buat direktori baru untuk menguji ekstensi. Karena ekstensi dikembangkan dari fungsi yang ada, jangan menguji dari folder tempat ekstensi dikonfigurasi karena tindakan tersebut juga akan mencoba men-deploy fungsi dan aturan Firebase bersamaan.

Menginstal dan menguji dengan emulator Firebase

  1. Buat direktori baru di sistem host Anda dan hubungkan direktori tersebut ke project Firebase Anda menggunakan firebase init.
mkdir sample-proj
cd sample-proj
firebase init --project=projectID-or-alias
  1. Dari direktori tersebut, jalankan firebase ext:install untuk menginstal ekstensi. Ganti /path/to/extension dengan jalur absolut ke direktori yang berisi file extension.yaml Anda. Tindakan ini akan memulai proses penginstalan untuk ekstensi Anda dan membuat file .env yang berisi konfigurasi Anda sebelum mengirimkan konfigurasi ke Firebase atau ke emulator.
firebase ext:install /path/to/extension
  • Karena Anda men-deploy project secara lokal, tentukan bahwa Anda ingin menggunakan file lokal, bukan Google Cloud Secret Manager.

da928c65ffa8ce15.png

  1. Mulai local emulator suite:
firebase emulators:start

Menginstal dan menguji dengan project Firebase sungguhan

Anda dapat menginstal ekstensi di project Firebase yang sebenarnya. Sebaiknya gunakan project uji untuk pengujian Anda. Gunakan alur kerja pengujian ini jika Anda ingin menguji seluruh alur ekstensi atau jika pemicu ekstensi Anda belum didukung oleh Firebase emulator suite (lihat Opsi emulator ekstensi). Saat ini, emulator mendukung fungsi yang dipicu permintaan HTTP dan fungsi yang dipicu peristiwa latar belakang untuk Cloud Firestore, Realtime Database, dan Pub/Sub.

  1. Buat direktori baru di sistem host Anda dan hubungkan direktori tersebut ke project Firebase Anda menggunakan firebase init.
cd ..
mkdir sample-proj
cd sample-proj
firebase init --project=projectID-or-alias
  1. Kemudian, dari direktori tersebut, jalankan firebase ext:install untuk menginstal ekstensi. Ganti /path/to/extension dengan jalur absolut ke direktori yang berisi file extension.yaml Anda. Tindakan ini akan memulai proses penginstalan untuk ekstensi Anda dan membuat file .env yang berisi konfigurasi Anda sebelum mengirimkan konfigurasi ke Firebase atau ke emulator.
firebase ext:install /path/to/extension
  • Karena Anda ingin men-deploy langsung ke Firebase, dan ingin menggunakan Google Cloud Secret Manager, Anda harus mengaktifkan Secret Manager API sebelum menginstal ekstensi.
  1. Deploy ke project Firebase Anda.
firebase deploy

Menguji ekstensi

  1. Setelah menjalankan firebase deploy atau firebase emulators:start, buka tab Firestore di Firebase console atau webview emulator, sebagaimana mestinya.
  2. Tambahkan dokumen ke dalam koleksi yang ditentukan oleh kolom x dan kolom y. Dalam hal ini, dokumen yang diperbarui berada di u/{uid} dengan kolom x yang bernilai xv dan kolom y yang bernilai yv.

Layar Emulator Firebase untuk menambahkan Rekaman Firestore

  1. Jika Anda berhasil menginstal ekstensi, ekstensi akan membuat kolom baru bernama hash di dokumen setelah Anda menyimpan kedua kolom.

Layar database Firestore dari emulator yang menampilkan hash yang ditambahkan

8. Selamat!

Anda telah berhasil mengonversi Cloud Function pertama menjadi Ekstensi Firebase.

Anda menambahkan file extension.yaml dan mengonfigurasinya sehingga developer dapat memilih cara men-deploy ekstensi Anda. Kemudian, Anda membuat dokumentasi pengguna yang memberikan panduan tentang tindakan yang harus dilakukan oleh developer ekstensi sebelum menyiapkan ekstensi dan langkah-langkah yang mungkin perlu mereka lakukan setelah berhasil menginstal ekstensi.

Sekarang Anda telah mengetahui langkah-langkah penting yang diperlukan untuk mengonversi Firebase Function menjadi Ekstensi Firebase yang dapat didistribusikan.

Apa selanjutnya?