Modello di eliminazione collettiva di Firestore

Il template Firestore Bulk Delete è una pipeline che legge le entità da Firestore con una determinata query GQL, quindi elimina tutte le entità corrispondenti nel progetto di destinazione selezionato. La pipeline può facoltativamente passare le entità Firestore con codifica JSON alla funzione definita dall'utente JavaScript, che puoi utilizzare per filtrare le entità restituendo valori null.

Requisiti della pipeline

• Firestore deve essere configurato nel progetto prima di eseguire il template.
• Se la lettura e l'eliminazione vengono eseguite da istanze Firestore separate, l'account di servizio worker di Dataflow deve disporre dell'autorizzazione per leggere da un'istanza ed eliminare dall'altra.
• Le scritture nel database devono essere abilitate nell'istanza Firestore.

Parametri del modello

Parametro	Descrizione
firestoreReadGqlQuery	Query GQL che specifica le entità da eliminare. L'utilizzo di una query solo per chiavi può migliorare le prestazioni. Ad esempio: "SELECT __key__ FROM MyKind".
firestoreReadProjectId	ID progetto dell'istanza Firestore da cui vuoi leggere le entità (utilizzando la query GQL) utilizzate per la corrispondenza.
firestoreDeleteProjectId	ID progetto dell'istanza Firestore da cui eliminare le entità corrispondenti. Può essere uguale a firestoreReadProjectId se vuoi leggere ed eliminare i dati all'interno della stessa istanza Firestore.
firestoreReadNamespace	(Facoltativo) Spazio dei nomi delle entità richieste. Imposta su "" per lo spazio dei nomi predefinito.
firestoreHintNumWorkers	(Facoltativo) Suggerimento per il numero previsto di worker nel passaggio di limitazione della rampa di Firestore. Il valore predefinito è 500.
javascriptTextTransformGcsPath	(Facoltativo) L'URI Cloud Storage del file .js che definisce la funzione definita dall'utente (UDF) JavaScript che vuoi utilizzare. Ad esempio: gs://my-bucket/my-udfs/my_file.js.
javascriptTextTransformFunctionName	(Facoltativo) Il nome della funzione definita dall'utente (UDF) JavaScript che vuoi utilizzare. Ad esempio, se il codice della funzione JavaScript è myTransform(inJson) { /*...do stuff...*/ }, il nome della funzione è myTransform. Per esempi di UDF JavaScript, consulta Esempi di UDF. Se questa funzione restituisce un valore non definito o null per una determinata entità Firestore, l'entità non viene eliminata.

Funzione definita dall'utente

Se vuoi, puoi estendere questo modello scrivendo una funzione definita dall'utente (UDF). Il template chiama la funzione definita dall'utente per ogni elemento di input. I payload degli elementi vengono serializzati come stringhe JSON. Per saperne di più, consulta Crea funzioni definite dall'utente per i template Dataflow.

Specifica della funzione

La funzione definita dall'utente ha la seguente specifica:

• Input: un'entità Firestore, serializzata come stringa JSON.
• Output: se vuoi mantenere l'entità e non eliminarla, restituisci null o undefined. In caso contrario, restituisci l'entità originale per l'eliminazione.

Esegui il modello

Console

1. Vai alla pagina Crea job da modello di Dataflow.
Vai a Crea job da modello
2. Nel campo Nome job, inserisci un nome job univoco.
3. (Facoltativo) Per Endpoint a livello di regione, seleziona un valore dal menu a discesa. La regione predefinita è us-central1.

   Per un elenco delle regioni in cui puoi eseguire un job Dataflow, consulta Località di Dataflow.

4. Dal menu a discesa Modello Dataflow, seleziona il modello Elimina in blocco le entità in Firestore.
5. Nei campi dei parametri forniti, inserisci i valori dei parametri.
6. Fai clic su Esegui job.

gcloud

Nota: per utilizzare Google Cloud CLI per eseguire i modelli classic, devi avere Google Cloud CLI versione 138.0.0 o successiva.

Nella shell o nel terminale, esegui il template:

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates/VERSION/Firestore_to_Firestore_Delete \
    --region REGION_NAME \
    --parameters \
firestoreReadGqlQuery="GQL_QUERY",\
firestoreReadProjectId=FIRESTORE_READ_AND_DELETE_PROJECT_ID,\
firestoreDeleteProjectId=FIRESTORE_READ_AND_DELETE_PROJECT_ID

Sostituisci quanto segue:

• JOB_NAME: un nome job univoco di tua scelta
• REGION_NAME: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempio us-central1
• VERSION: la versione del template che vuoi utilizzare

  Puoi utilizzare i seguenti valori:

  • latest per utilizzare l'ultima versione del template, disponibile nella cartella padre senza data nel bucket: gs://dataflow-templates/latest/
  • il nome della versione, ad esempio 2023-09-12-00_RC00, per utilizzare una versione specifica del template, che si trova nidificata nella rispettiva cartella padre con data nel bucket: gs://dataflow-templates/
  Attenzione: l'ultima versione dei template potrebbe essere aggiornata con modifiche che provocano un errore. Gli ambienti di produzione devono utilizzare i template conservati nella cartella padre con data più recente per evitare che queste modifiche che provocano un errore influiscano sui flussi di lavoro di produzione.
• GQL_QUERY: la query che utilizzerai per trovare le entità da eliminare
• FIRESTORE_READ_AND_DELETE_PROJECT_ID: l'ID progetto dell'istanza Firestore. Questo esempio legge ed elimina dalla stessa istanza Firestore.

API

Per eseguire il template utilizzando l'API REST, invia una richiesta POST HTTP. Per saperne di più sull'API e sui relativi ambiti di autorizzazione, consulta projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates/VERSION/Firestore_to_Firestore_Delete
{
   "jobName": "JOB_NAME",
   "parameters": {
       "firestoreReadGqlQuery": "GQL_QUERY",
       "firestoreReadProjectId": "FIRESTORE_READ_AND_DELETE_PROJECT_ID",
       "firestoreDeleteProjectId": "FIRESTORE_READ_AND_DELETE_PROJECT_ID"
   },
   "environment": { "zone": "us-central1-f" }
}

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto Google Cloud in cui vuoi eseguire il job Dataflow
• JOB_NAME: un nome job univoco di tua scelta
• LOCATION: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempio us-central1
• VERSION: la versione del template che vuoi utilizzare

  Puoi utilizzare i seguenti valori:

  • latest per utilizzare l'ultima versione del template, disponibile nella cartella padre senza data nel bucket: gs://dataflow-templates/latest/
  • il nome della versione, ad esempio 2023-09-12-00_RC00, per utilizzare una versione specifica del template, che si trova nidificata nella rispettiva cartella padre con data nel bucket: gs://dataflow-templates/
  Attenzione: l'ultima versione dei template potrebbe essere aggiornata con modifiche che provocano un errore. Gli ambienti di produzione devono utilizzare i template conservati nella cartella padre con data più recente per evitare che queste modifiche che provocano un errore influiscano sui flussi di lavoro di produzione.
• GQL_QUERY: la query che utilizzerai per trovare le entità da eliminare
• FIRESTORE_READ_AND_DELETE_PROJECT_ID: l'ID progetto dell'istanza Firestore. Questo esempio legge ed elimina dalla stessa istanza Firestore.

Codice sorgente del template

Java

/*
 * Copyright (C) 2018 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.google.cloud.teleport.templates;

import com.google.cloud.teleport.metadata.Template;
import com.google.cloud.teleport.metadata.TemplateCategory;
import com.google.cloud.teleport.templates.DatastoreToDatastoreDelete.DatastoreToDatastoreDeleteOptions;
import com.google.cloud.teleport.templates.common.DatastoreConverters.DatastoreDeleteEntityJson;
import com.google.cloud.teleport.templates.common.DatastoreConverters.DatastoreDeleteOptions;
import com.google.cloud.teleport.templates.common.DatastoreConverters.DatastoreReadOptions;
import com.google.cloud.teleport.templates.common.DatastoreConverters.ReadJsonEntities;
import com.google.cloud.teleport.templates.common.FirestoreNestedValueProvider;
import com.google.cloud.teleport.templates.common.JavascriptTextTransformer.JavascriptTextTransformerOptions;
import com.google.cloud.teleport.templates.common.JavascriptTextTransformer.TransformTextViaJavascript;
import org.apache.beam.sdk.Pipeline;
import org.apache.beam.sdk.options.PipelineOptions;
import org.apache.beam.sdk.options.PipelineOptionsFactory;
import org.apache.beam.sdk.options.ValueProvider;

/**
 * Dataflow template which deletes pulled Datastore Entities.
 *
 * <p>Check out <a
 * href="https://github.com/GoogleCloudPlatform/DataflowTemplates/blob/main/v1/README_Datastore_to_Datastore_Delete.md">README
 * Datastore</a> or <a
 * href="https://github.com/GoogleCloudPlatform/DataflowTemplates/blob/main/v1/README_Firestore_to_Firestore_Delete.md">README
 * Firestore</a> for instructions on how to use or modify this template.
 */
@Template(
    name = "Datastore_to_Datastore_Delete",
    category = TemplateCategory.LEGACY,
    displayName = "Bulk Delete Entities in Datastore [Deprecated]",
    description =
        "A pipeline which reads in Entities (via a GQL query) from Datastore, optionally passes in the JSON encoded "
            + "Entities to a JavaScript UDF, and then deletes all matching Entities in the selected target project.",
    optionsClass = DatastoreToDatastoreDeleteOptions.class,
    skipOptions = {
      "firestoreReadGqlQuery",
      "firestoreReadProjectId",
      "firestoreReadNamespace",
      "firestoreDeleteProjectId",
      "firestoreHintNumWorkers",
      "javascriptTextTransformReloadIntervalMinutes"
    },
    documentation =
        "https://cloud.google.com/dataflow/docs/guides/templates/provided/datastore-bulk-delete",
    contactInformation = "https://cloud.google.com/support",
    requirements = {
      "Datastore must be set up in the project prior to running the template.",
      "If reading and deleting from separate Datastore instances, the Dataflow <a href=\"https://cloud.google.com/dataflow/docs/concepts/security-and-permissions#worker-service-account\">Worker Service Account</a> must have permission to read from one instance and delete from the other."
    })
@Template(
    name = "Firestore_to_Firestore_Delete",
    category = TemplateCategory.UTILITIES,
    displayName = "Bulk Delete Entities in Firestore (Datastore mode)",
    description =
        "A pipeline which reads in Entities (via a GQL query) from Firestore, optionally passes in the JSON encoded "
            + "Entities to a JavaScript UDF, and then deletes all matching Entities in the selected target project.",
    optionsClass = DatastoreToDatastoreDeleteOptions.class,
    optionsOrder = {
      DatastoreReadOptions.class,
      DatastoreDeleteOptions.class,
      JavascriptTextTransformerOptions.class
    },
    skipOptions = {
      "datastoreReadGqlQuery",
      "datastoreReadProjectId",
      "datastoreReadNamespace",
      "datastoreDeleteProjectId",
      "datastoreHintNumWorkers",
      "javascriptTextTransformReloadIntervalMinutes"
    },
    documentation =
        "https://cloud.google.com/dataflow/docs/guides/templates/provided/firestore-bulk-delete",
    contactInformation = "https://cloud.google.com/support",
    requirements = {
      "Firestore must be set up in the project prior to running the template.",
      "If reading and deleting from separate Firestore instances, the Dataflow <a href=\"https://cloud.google.com/dataflow/docs/concepts/security-and-permissions#worker-service-account\">Worker Service Account</a> must have permission to read from one instance and delete from the other."
    })
public class DatastoreToDatastoreDelete {

  public static <T> ValueProvider<T> selectProvidedInput(
      ValueProvider<T> datastoreInput, ValueProvider<T> firestoreInput) {
    return new FirestoreNestedValueProvider<T>(datastoreInput, firestoreInput);
  }

  /** Custom PipelineOptions. */
  public interface DatastoreToDatastoreDeleteOptions
      extends PipelineOptions,
          DatastoreReadOptions,
          JavascriptTextTransformerOptions,
          DatastoreDeleteOptions {}

  /**
   * Runs a pipeline which reads in Entities from datastore, passes in the JSON encoded Entities to
   * a Javascript UDF, and deletes all the Entities.
   *
   * <p>If the UDF returns value of undefined or null for a given Entity, then that Entity will not
   * be deleted.
   *
   * @param args arguments to the pipeline
   */
  public static void main(String[] args) {
    DatastoreToDatastoreDeleteOptions options =
        PipelineOptionsFactory.fromArgs(args)
            .withValidation()
            .as(DatastoreToDatastoreDeleteOptions.class);

    Pipeline pipeline = Pipeline.create(options);

    pipeline
        .apply(
            ReadJsonEntities.newBuilder()
                .setGqlQuery(
                    selectProvidedInput(
                        options.getDatastoreReadGqlQuery(), options.getFirestoreReadGqlQuery()))
                .setProjectId(
                    selectProvidedInput(
                        options.getDatastoreReadProjectId(), options.getFirestoreReadProjectId()))
                .setNamespace(
                    selectProvidedInput(
                        options.getDatastoreReadNamespace(), options.getFirestoreReadNamespace()))
                .build())
        .apply(
            TransformTextViaJavascript.newBuilder()
                .setFileSystemPath(options.getJavascriptTextTransformGcsPath())
                .setFunctionName(options.getJavascriptTextTransformFunctionName())
                .build())
        .apply(
            DatastoreDeleteEntityJson.newBuilder()
                .setProjectId(
                    selectProvidedInput(
                        options.getDatastoreDeleteProjectId(),
                        options.getFirestoreDeleteProjectId()))
                .setHintNumWorkers(
                    selectProvidedInput(
                        options.getDatastoreHintNumWorkers(), options.getFirestoreHintNumWorkers()))
                .build());

    pipeline.run();
  }
}

Passaggi successivi

• Scopri di più sui template Dataflow.
• Consulta l'elenco dei modelli forniti da Google.