Memperluas dengan Cloud Functions (generasi ke-2)

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

Memperluas fungsi Firestore dengan Cloud Functions (generasi ke-2)

Cloud Functions (generasi ke-2) mendukung pemicu peristiwa Firestore berikut sehingga Anda dapat membuat pengendali yang terkait dengan peristiwa Firestore:

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

Peristiwa Firestore hanya dipicu jika ada perubahan dokumen. Pembaruan terhadap dokumen Firestore yang tidak mengubah data (penulisan tanpa pengoperasian), tidak menghasilkan peristiwa penulisan atau pembaruan. Peristiwa tidak dapat ditambahkan ke kolom tertentu.

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 Firestore

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

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

Filter peristiwa pemicu

Saat menentukan filter peristiwa, Anda dapat menentukan kecocokan dokumen yang tepat atau pola jalur. Gunakan pola jalur untuk mencocokkan beberapa dokumen dengan karakter pengganti, * atau **.

Misalnya, Anda dapat merespons perubahan pada dokumen berikut:

users/marie

Gunakan karakter pengganti, * atau **, untuk merespons perubahan dalam dokumen 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. Misalnya, users/{userId}.

Contoh:

Pola	Deskripsi
`/users/*` atau `/users/{userId}`	Mencocokkan semua dokumen di koleksi `/users`. Tidak cocok dengan dokumen di subkoleksi seperti `/users/marie/messages/33e2IxYBD9enzS50SJ68`
`/users/**`	Mencocokkan semua dokumen dalam koleksi `/users` dan dokumen di subkoleksi seperti `/users/marie/messages/33e2IxYBD9enzS50SJ68`

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

Pemicu Anda harus selalu menunjuk ke sebuah dokumen, meskipun Anda menggunakan karakter pengganti. Misalnya, users/{userId=*}/{messageCollectionId=*} tidak valid karena {messageCollectionId=*} adalah sebuah koleksi. Namun, users/{userId=*}/{messageCollectionId}/{messageId=*} valid karena {messageId=*} akan selalu mengarah ke dokumen.

Contoh fungsi

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

value: Objek Document yang berisi snapshot dokumen pascaoperasi. Kolom ini tidak diisi untuk peristiwa penghapusan.
old_value: Objek Document yang berisi snapshot dokumen pra-operasi. Kolom ini hanya diisi untuk peristiwa pembaruan dan penghapusan.

Go

Untuk mengautentikasi ke Firestore, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.


// Package hellofirestore contains a Cloud Event Function triggered by a Cloud Firestore event.
package hellofirestore

import (
	"context"
	"fmt"

	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
	"github.com/cloudevents/sdk-go/v2/event"
	"github.com/googleapis/google-cloudevents-go/cloud/firestoredata"
	"google.golang.org/protobuf/proto"
)

func init() {
	functions.CloudEvent("helloFirestore", HelloFirestore)
}

// HelloFirestore is triggered by a change to a Firestore document.
func HelloFirestore(ctx context.Context, event event.Event) error {
	var data firestoredata.DocumentEventData
	if err := proto.Unmarshal(event.Data(), &data); err != nil {
		return fmt.Errorf("proto.Unmarshal: %w", err)
	}

	fmt.Printf("Function triggered by change to: %v\n", event.Source())
	fmt.Printf("Old value: %+v\n", data.GetOldValue())
	fmt.Printf("New value: %+v\n", data.GetValue())
	return nil
}

Java

Untuk mengautentikasi ke Firestore, 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.firestore.v1.DocumentEventData;
import com.google.protobuf.InvalidProtocolBufferException;
import io.cloudevents.CloudEvent;
import java.util.logging.Logger;

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

  @Override
  public void accept(CloudEvent event) throws InvalidProtocolBufferException {
    DocumentEventData firestorEventData = DocumentEventData.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(firestorEventData.getOldValue().toString());

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

Node.js

Untuk mengautentikasi ke Firestore, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

Gunakan protobufjs untuk mendekode data peristiwa. Sertakan google.events.cloud.firestore.v1 data.proto dalam sumber Anda.

/**
 * Cloud Event Function triggered by a change to a Firestore document.
 */
const functions = require('@google-cloud/functions-framework');
const protobuf = require('protobufjs');

functions.cloudEvent('helloFirestore', async cloudEvent => {
  console.log(`Function triggered by event on: ${cloudEvent.source}`);
  console.log(`Event type: ${cloudEvent.type}`);

  console.log('Loading protos...');
  const root = await protobuf.load('data.proto');
  const DocumentEventData = root.lookupType(
    'google.events.cloud.firestore.v1.DocumentEventData'
  );

  console.log('Decoding data...');
  const firestoreReceived = DocumentEventData.decode(cloudEvent.data);

  console.log('\nOld value:');
  console.log(JSON.stringify(firestoreReceived.oldValue, null, 2));

  console.log('\nNew value:');
  console.log(JSON.stringify(firestoreReceived.value, null, 2));
});

Python

Untuk mengautentikasi ke Firestore, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

from cloudevents.http import CloudEvent
import functions_framework
from google.events.cloud import firestore

@functions_framework.cloud_event
def hello_firestore(cloud_event: CloudEvent) -> None:
    """Triggers by a change to a Firestore document.

    Args:
        cloud_event: cloud event with information on the firestore event trigger
    """
    firestore_payload = firestore.DocumentEventData()
    firestore_payload._pb.ParseFromString(cloud_event.data)

    print(f"Function triggered by change to: {cloud_event['source']}")

    print("\nOld value:")
    print(firestore_payload.old_value)

    print("\nNew value:")
    print(firestore_payload.value)

C#

Untuk mengautentikasi ke Firestore, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.Firestore.V1;
using Microsoft.Extensions.Logging;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;

namespace FirebaseFirestore;

public class Function : ICloudEventFunction<DocumentEventData>
{
    private readonly ILogger _logger;

    public Function(ILogger<Function> logger) =>
        _logger = logger;

    public Task HandleAsync(CloudEvent cloudEvent, DocumentEventData data, CancellationToken cancellationToken)
    {
        _logger.LogInformation("Function triggered by event on {subject}", cloudEvent.Subject);
        _logger.LogInformation("Event type: {type}", cloudEvent.Type);
        MaybeLogDocument("Old value", data.OldValue);
        MaybeLogDocument("New value", data.Value);

        // In this example, we don't need to perform any asynchronous operations, so the
        // method doesn't need to be declared async.
        return Task.CompletedTask;
    }

    /// <summary>
    /// Logs the names and values of the fields in a document in a very simplistic way.
    /// </summary>
    private void MaybeLogDocument(string message, Document document)
    {
        if (document is null)
        {
            return;
        }

        // ConvertFields converts the Firestore representation into a .NET-friendly
        // representation.
        IReadOnlyDictionary<string, object> fields = document.ConvertFields();
        var fieldNamesAndTypes = fields
            .OrderBy(pair => pair.Key)
            .Select(pair => $"{pair.Key}: {pair.Value}");
        _logger.LogInformation(message + ": {fields}", string.Join(", ", fieldNamesAndTypes));
    }
}

Contoh berikut mengonversi string yang ditambahkan ke kolom original dari dokumen yang terpengaruh menjadi huruf kapital dan menulis nilai baru ke dokumen yang sama:

Go

Untuk mengautentikasi ke Firestore, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.


// Package upper contains a Firestore Cloud Function.
package upper

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"strings"

	"cloud.google.com/go/firestore"
	firebase "firebase.google.com/go/v4"
	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
	"github.com/cloudevents/sdk-go/v2/event"
	"github.com/googleapis/google-cloudevents-go/cloud/firestoredata"
	"google.golang.org/protobuf/proto"
)

// set the GOOGLE_CLOUD_PROJECT environment variable when deploying.
var projectID = os.Getenv("GOOGLE_CLOUD_PROJECT")

// client is a Firestore client, reused between function invocations.
var client *firestore.Client

func init() {
	// Use the application default credentials.
	conf := &firebase.Config{ProjectID: projectID}

	// Use context.Background() because the app/client should persist across
	// invocations.
	ctx := context.Background()

	app, err := firebase.NewApp(ctx, conf)
	if err != nil {
		log.Fatalf("firebase.NewApp: %v", err)
	}

	client, err = app.Firestore(ctx)
	if err != nil {
		log.Fatalf("app.Firestore: %v", err)
	}

	// Register cloud event function
	functions.CloudEvent("MakeUpperCase", MakeUpperCase)
}

// MakeUpperCase is triggered by a change to a Firestore document. It updates
// the `original` value of the document to upper case.
func MakeUpperCase(ctx context.Context, e event.Event) error {
	var data firestoredata.DocumentEventData
	if err := proto.Unmarshal(e.Data(), &data); err != nil {
		return fmt.Errorf("proto.Unmarshal: %w", err)
	}

	if data.GetValue() == nil {
		return errors.New("Invalid message: 'Value' not present")
	}

	fullPath := strings.Split(data.GetValue().GetName(), "/documents/")[1]
	pathParts := strings.Split(fullPath, "/")
	collection := pathParts[0]
	doc := strings.Join(pathParts[1:], "/")

	var originalStringValue string
	if v, ok := data.GetValue().GetFields()["original"]; ok {
		originalStringValue = v.GetStringValue()
	} else {
		return errors.New("Document did not contain field \"original\"")
	}

	newValue := strings.ToUpper(originalStringValue)
	if originalStringValue == newValue {
		log.Printf("%q is already upper case: skipping", originalStringValue)
		return nil
	}
	log.Printf("Replacing value: %q -> %q", originalStringValue, newValue)

	newDocumentEntry := map[string]string{"original": newValue}
	_, err := client.Collection(collection).Doc(doc).Set(ctx, newDocumentEntry)
	if err != nil {
		return fmt.Errorf("Set: %w", err)
	}
	return nil
}

Java

Untuk mengautentikasi ke Firestore, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

import com.google.cloud.firestore.Firestore;
import com.google.cloud.firestore.FirestoreOptions;
import com.google.cloud.firestore.SetOptions;
import com.google.cloud.functions.CloudEventsFunction;
import com.google.events.cloud.firestore.v1.DocumentEventData;
import com.google.events.cloud.firestore.v1.Value;
import com.google.protobuf.InvalidProtocolBufferException;
import io.cloudevents.CloudEvent;
import java.util.Map;
import java.util.concurrent.ExecutionException;
import java.util.logging.Logger;

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

  private static final String FIELD_KEY = "original";
  private static final String APPLICATION_PROTOBUF = "application/protobuf";

  public FirebaseFirestoreReactive() {
    this(FirestoreOptions.getDefaultInstance().getService());
  }

  public FirebaseFirestoreReactive(Firestore firestore) {
    this.firestore = firestore;
  }

  @Override
  public void accept(CloudEvent event)
      throws InvalidProtocolBufferException, InterruptedException, ExecutionException {
    if (event.getData() == null) {
      logger.warning("No data found in event!");
      return;
    }

    if (!event.getDataContentType().equals(APPLICATION_PROTOBUF)) {
      logger.warning(String.format("Found unexpected content type %s, expected %s",
          event.getDataContentType(),
          APPLICATION_PROTOBUF));
      return;
    }

    DocumentEventData firestoreEventData = DocumentEventData
        .parseFrom(event.getData().toBytes());

    // Get the fields from the post-operation document snapshot
    // https://firebase.google.com/docs/firestore/reference/rest/v1/projects.databases.documents#Document
    Map<String, Value> fields = firestoreEventData.getValue().getFieldsMap();
    if (!fields.containsKey(FIELD_KEY)) {
      logger.warning("Document does not contain original field");
      return;
    }
    String currValue = fields.get(FIELD_KEY).getStringValue();
    String newValue = currValue.toUpperCase();

    if (currValue.equals(newValue)) {
      logger.info("Value is already upper-case");
      return;
    }

    // Retrieve the document name from the resource path:
    // projects/{project_id}/databases/{database_id}/documents/{document_path}
    String affectedDoc = firestoreEventData.getValue()
        .getName()
        .split("/documents/")[1]
        .replace("\"", "");

    logger.info(String.format("Replacing values: %s --> %s", currValue, newValue));

    // Wait for the async call to complete
    this.firestore
        .document(affectedDoc)
        .set(Map.of(FIELD_KEY, newValue), SetOptions.merge())
        .get();
  }
}

Node.js

Untuk mengautentikasi ke Firestore, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

Gunakan protobufjs untuk mendekode data peristiwa. Sertakan google.events.cloud.firestore.v1 data.proto dalam sumber Anda.

const functions = require('@google-cloud/functions-framework');
const Firestore = require('@google-cloud/firestore');
const protobuf = require('protobufjs');

const firestore = new Firestore({
  projectId: process.env.GOOGLE_CLOUD_PROJECT,
});

// Converts strings added to /messages/{pushId}/original to uppercase
functions.cloudEvent('makeUpperCase', async cloudEvent => {
  console.log('Loading protos...');
  const root = await protobuf.load('data.proto');
  const DocumentEventData = root.lookupType(
    'google.events.cloud.firestore.v1.DocumentEventData'
  );

  console.log('Decoding data...');
  const firestoreReceived = DocumentEventData.decode(cloudEvent.data);

  const resource = firestoreReceived.value.name;
  const affectedDoc = firestore.doc(resource.split('/documents/')[1]);

  const curValue = firestoreReceived.value.fields.original.stringValue;
  const newValue = curValue.toUpperCase();

  if (curValue === newValue) {
    // Value is already upper-case
    // Don't perform a(nother) write to avoid infinite loops
    console.log('Value is already upper-case.');
    return;
  }

  console.log(`Replacing value: ${curValue} --> ${newValue}`);
  affectedDoc.set({
    original: newValue,
  });
});

Python

Untuk mengautentikasi ke Firestore, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

from cloudevents.http import CloudEvent
import functions_framework
from google.cloud import firestore
from google.events.cloud import firestore as firestoredata

client = firestore.Client()

# Converts strings added to /messages/{pushId}/original to uppercase
@functions_framework.cloud_event
def make_upper_case(cloud_event: CloudEvent) -> None:
    firestore_payload = firestoredata.DocumentEventData()
    firestore_payload._pb.ParseFromString(cloud_event.data)

    path_parts = firestore_payload.value.name.split("/")
    separator_idx = path_parts.index("documents")
    collection_path = path_parts[separator_idx + 1]
    document_path = "/".join(path_parts[(separator_idx + 2) :])

    print(f"Collection path: {collection_path}")
    print(f"Document path: {document_path}")

    affected_doc = client.collection(collection_path).document(document_path)

    cur_value = firestore_payload.value.fields["original"].string_value
    new_value = cur_value.upper()

    if cur_value != new_value:
        print(f"Replacing value: {cur_value} --> {new_value}")
        affected_doc.set({"original": new_value})
    else:
        # Value is already upper-case
        # Don't perform a second write (which can trigger an infinite loop)
        print("Value is already upper-case.")

C#

Untuk mengautentikasi ke Firestore, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

using CloudNative.CloudEvents;
using Google.Cloud.Firestore;
using Google.Cloud.Functions.Framework;
using Google.Cloud.Functions.Hosting;
using Google.Events.Protobuf.Cloud.Firestore.V1;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace FirestoreReactive;

public class Startup : FunctionsStartup
{
    public override void ConfigureServices(WebHostBuilderContext context, IServiceCollection services) =>
        services.AddSingleton(FirestoreDb.Create());
}

// Register the startup class to provide the Firestore dependency.
[FunctionsStartup(typeof(Startup))]
public class Function : ICloudEventFunction<DocumentEventData>
{
    private readonly ILogger _logger;
    private readonly FirestoreDb _firestoreDb;

    public Function(ILogger<Function> logger, FirestoreDb firestoreDb) =>
        (_logger, _firestoreDb) = (logger, firestoreDb);

    public async Task HandleAsync(CloudEvent cloudEvent, DocumentEventData data, CancellationToken cancellationToken)
    {
        // Get the recently-written value. This expression will result in a null value
        // if any of the following is true:
        // - The event doesn't contain a "new" document
        // - The value doesn't contain a field called "original"
        // - The "original" field isn't a string
        string currentValue = data.Value?.ConvertFields().GetValueOrDefault("original") as string;
        if (currentValue is null)
        {
            _logger.LogWarning($"Event did not contain a suitable document");
            return;
        }

        string newValue = currentValue.ToUpperInvariant();
        if (newValue == currentValue)
        {
            _logger.LogInformation("Value is already upper-cased; no replacement necessary");
            return;
        }

        // The CloudEvent subject is "documents/x/y/...".
        // The Firestore SDK FirestoreDb.Document method expects a reference relative to
        // "documents" (so just the "x/y/..." part). This may be simplified over time.
        if (cloudEvent.Subject is null || !cloudEvent.Subject.StartsWith("documents/"))
        {
            _logger.LogWarning("CloudEvent subject is not a document reference.");
            return;
        }
        string documentPath = cloudEvent.Subject.Substring("documents/".Length);

        _logger.LogInformation("Replacing '{current}' with '{new}' in '{path}'", currentValue, newValue, documentPath);
        await _firestoreDb.Document(documentPath).UpdateAsync("original", newValue);
    }
}

Menyertakan dependensi proto di sumber Anda

Anda harus menyertakan file data.proto Firestore 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 menambahkan data tambahan tentang database dan dokumen yang terlibat dalam peristiwa. Anda dapat mengakses atribut ini sebagai berikut:

Java

logger.info("Function triggered by event on: " + event.getSource());
logger.info("Event type: " + event.getType());
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 document: " + event.getExtension("document"));
// For withAuthContext events
logger.info("Auth information: " + event.getExtension("authid"));
logger.info("Auth information: " + event.getExtension("authtype"));

Node.js

console.log(`Function triggered by event on: ${cloudEvent.source}`);
console.log(`Event type: ${cloudEvent.type}`);
console.log(`Event time: ${cloudEvent.time}`);
console.log(`Event project: ${cloudEvent.project}`);
console.log(`Event location: ${cloudEvent.location}`);
console.log(`Database name: ${cloudEvent.database}`);
console.log(`Document name: ${cloudEvent.document}`);
// For withAuthContext events
console.log(`Auth information: ${cloudEvent.authid}`);
console.log(`Auth information: ${cloudEvent.authtype}`);

Python

print(f"Function triggered by change to: {cloud_event['source']}")
print(f"Event type: {cloud_event['type']}")
print(f"Event time: {cloud_event['time']}")
print(f"Event project: {cloud_event['project']}")
print(f"Location: {cloud_event['location']}")
print(f"Database name: {cloud_event['database']}")
print(f"Document: {cloud_event['document']}")
// For withAuthContext events
print(f"Auth information: {cloud_event['authid']}")
print(f"Auth information: {cloud_event['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

gcloud

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 YOUR_FUNCTION_NAME \
--gen2 \
--region=FUNCTION_LOCATION \
--trigger-location=TRIGGER_LOCATION \
--runtime=YOUR_RUNTIME \
--source=YOUR_SOURCE_LOCATION \
--entry-point=YOUR_CODE_ENTRYPOINT \
--trigger-event-filters="type=EVENT_FILTER_TYPE" \
--trigger-event-filters="database=DATABASE" \
--trigger-event-filters-path-pattern="document=DOCUMENT" \
```
Argumen pertama, YOUR_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.
- 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 menentukan region tempat men-deploy fungsi Anda.
  
  Untuk memaksimalkan kedekatan, tetapkan ke region yang dekat dengan database Firestore Anda. Jika database Firestore Anda berada di lokasi multi-region, tetapkan 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 menentukan lokasi pemicu. Anda harus menetapkan flag ini ke lokasi database Firestore.
- Flag --runtime menentukan runtime bahasa yang digunakan fungsi Anda. Cloud Functions mendukung beberapa runtime. Lihat Runtime untuk mengetahui informasi lebih lanjut.
- Flag --source menentukan lokasi kode sumber fungsi Anda. Lihat informasi berikut untuk mengetahui detailnya:
- Flag --entry-point menentukan titik masuk ke fungsi Anda dalam kode sumber. Ini adalah kode yang akan dijalankan saat fungsi Anda berjalan. Nilai flag ini harus berupa nama fungsi atau nama class yang sepenuhnya memenuhi syarat yang ada dalam kode sumber Anda. Lihat Titik entri fungsi untuk informasi selengkapnya.
- EVENT_FILTER_TYPE: Firestore mendukung jenis peristiwa berikut.
  - google.cloud.firestore.document.v1.created: peristiwa dikirim saat dokumen ditulis untuk pertama kalinya.
  - google.cloud.firestore.document.v1.updated: peristiwa dikirim saat dokumen sudah ada dan nilainya berubah.
  - google.cloud.firestore.document.v1.deleted: peristiwa dikirim saat dokumen dihapus.
  - google.cloud.firestore.document.v1.written: peristiwa dikirim saat dokumen dibuat, diperbarui, atau dihapus.
  - google.cloud.firestore.document.v1.created.withAuthContext: peristiwa dikirim saat dokumen ditulis untuk pertama kalinya dan peristiwa tersebut menyertakan informasi autentikasi tambahan
  - google.cloud.firestore.document.v1.updated.withAuthContext: peristiwa dikirim saat dokumen sudah ada dan nilainya berubah. Menyertakan informasi autentikasi tambahan
  - google.cloud.firestore.document.v1.deleted.withAuthContext: peristiwa dikirim saat dokumen dihapus. Menyertakan informasi autentikasi tambahan
  - google.cloud.firestore.document.v1.written.withAuthContext: peristiwa dikirim saat dokumen dibuat, diperbarui, atau dihapus dan peristiwa. Menyertakan informasi autentikasi tambahan
- DATABASE: database Firestore. Untuk nama database default, gunakan (default).
- DOCUMENT: jalur database yang memicu peristiwa saat data dibuat, diperbarui, atau dihapus. Operator dapat berupa salah satu dari hal berikut:
  - Sama; misalnya, --trigger-event-filters=document='users/marie'
  - Pola jalur; misalnya, --trigger-event-filters-path-pattern=document='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-firestore-node \
--gen2 \
--region=us-west2 \
--trigger-location=us-west2 \
--runtime=nodejs18 \
--source=gs://CLOUD_STORAGE_BUCKET/firestoreEventFunction.zip \
--entry-point=makeUpperCase \
--trigger-event-filters=type=google.cloud.firestore.document.v1.written \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern=document='messages/{pushId}'

Deploy fungsi untuk database di multi-region nam5:

gcloud functions deploy gcfv2-trigger-firestore-python \
--gen2 \
--region=us-central1 \
--trigger-location=nam5 \
--runtime=python311 \
--source=gs://CLOUD_STORAGE_BUCKET/firestoreEventFunction.zip \
--entry-point=make_upper_case \
--trigger-event-filters=type=google.cloud.firestore.document.v1.written.withAuthContext \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern=document='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.

Lokasi Eventarc dan Firestore

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`

Perbedaan antara Cloud Functions generasi ke-2 dan generasi ke-1

Cloud Functions (generasi ke-2) menggunakan peristiwa Eventarc untuk semua runtime. Sebelumnya, Cloud Functions (generasi ke-1) menggunakan peristiwa Eventarc hanya untuk beberapa runtime. Peristiwa Eventarc memperkenalkan perbedaan berikut dengan Cloud Functions (generasi ke-1).

Pemicu Firestore untuk Eventarc mendukung tujuan tambahan selain Cloud Functions. Anda dapat merutekan CloudEvents ke sejumlah tujuan termasuk, tetapi tidak terbatas pada Cloud Run, GKE, dan Alur kerja.
Pemicu Firestore untuk Eventarc mengambil definisi pemicu di awal operasi tulis database dan menggunakan definisi tersebut untuk menentukan apakah Firestore harus memunculkan peristiwa. Operasi tulis tidak memperhitungkan perubahan apa pun untuk memicu definisi yang mungkin terjadi saat berjalan.

Cloud Functions (generasi ke-1) mengambil definisi pemicu selama evaluasi penulisan database, dan perubahan pada pemicu selama evaluasi dapat memengaruhi apakah Firestore memunculkan suatu peristiwa atau tidak.

Untuk mengetahui detail selengkapnya, lihat Perbandingan versi Cloud Functions.