Esta página se ha traducido con Cloud Translation API.

Plantilla de texto de Cloud Storage a Firestore

La plantilla de texto de Cloud Storage a Firestore es una canalización por lotes que importa documentos JSON almacenados en Cloud Storage a Firestore.

Requisitos del flujo de procesamiento

Debes habilitar Firestore en el proyecto de destino.

Formato de entrada

Cada archivo de entrada debe contener JSON delimitado por saltos de línea, donde cada línea contiene una representación JSON de un tipo de datos Entity de Datastore.

Por ejemplo, el siguiente JSON representa un documento de una colección llamada Users. El ejemplo se ha formateado para facilitar la lectura, pero cada documento debe aparecer como una sola línea de entrada.

{
  "key": {
    "partitionId": {
      "projectId": "my-project"
    },
    "path": [
      {
        "kind": "users",
        "name": "alovelace"
      }
    ]
  },
  "properties": {
    "first": {
      "stringValue": "Ada"
    },
    "last": {
      "stringValue": "Lovelace"
    },
    "born": {
      "integerValue": "1815",
      "excludeFromIndexes": true
    }
  }
}

Para obtener más información sobre el modelo de documento, consulta Entidades, propiedades y claves.

Parámetros de plantilla

Parámetros obligatorios

textReadPattern patrón de ruta de Cloud Storage que especifica la ubicación de los archivos de datos de texto. Por ejemplo, gs://mybucket/somepath/*.json.
firestoreWriteProjectId ID del proyecto de Google Cloud en el que se escribirán las entidades de Firestore.
errorWritePath archivo de salida del registro de errores que se va a usar en caso de que se produzcan errores de escritura durante el procesamiento. Por ejemplo, gs://your-bucket/errors/.

Parámetros opcionales

javascriptTextTransformGcsPath el URI de Cloud Storage del archivo .js que define la función de JavaScript definida por el usuario (UDF) que se va a usar. Por ejemplo, gs://my-bucket/my-udfs/my_file.js.
javascriptTextTransformFunctionName nombre de la función definida por el usuario (UDF) de JavaScript que se va a usar. Por ejemplo, si el código de la función de JavaScript es myTransform(inJson) { /*...do stuff...*/ }, el nombre de la función es myTransform. Para ver ejemplos de UDFs de JavaScript, consulta Ejemplos de UDFs (https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples).
firestoreHintNumWorkers sugerencia sobre el número de trabajadores esperado en el paso de limitación de la aceleración de Firestore. El valor predeterminado es 500.

Función definida por el usuario

También puedes ampliar esta plantilla escribiendo una función definida por el usuario (UDF). La plantilla llama a la función definida por el usuario para cada elemento de entrada. Las cargas útiles de los elementos se serializan como cadenas JSON. Para obtener más información, consulta el artículo sobre cómo crear funciones definidas por el usuario para plantillas de Dataflow.

Especificación de la función

La función definida por el usuario tiene las siguientes especificaciones:

Entrada: una línea de texto de un archivo de entrada de Cloud Storage.
Salida: un Entity, serializado como una cadena JSON.

Ejecutar la plantilla

Consola

Ve a la página Crear tarea a partir de plantilla de Dataflow.

Ir a Crear tarea a partir de plantilla

En el campo Nombre de la tarea, introduce un nombre único.
Opcional: En Endpoint regional, seleccione un valor en el menú desplegable. La región predeterminada es us-central1.
Para ver una lista de las regiones en las que puedes ejecutar una tarea de Dataflow, consulta Ubicaciones de Dataflow.
En el menú desplegable Plantilla de flujo de datos, seleccione the Text Files on Cloud Storage to Firestore template.
En los campos de parámetros proporcionados, introduzca los valores de los parámetros.
Haz clic en Ejecutar trabajo.

gcloud

En tu shell o terminal, ejecuta la plantilla:

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates-REGION_NAME/VERSION/GCS_Text_to_Firestore \
    --region REGION_NAME \
    --parameters \
textReadPattern=PATH_TO_INPUT_TEXT_FILES,\
javascriptTextTransformGcsPath=PATH_TO_JAVASCRIPT_UDF_FILE,\
javascriptTextTransformFunctionName=JAVASCRIPT_FUNCTION,\
firestoreWriteProjectId=PROJECT_ID,\
errorWritePath=ERROR_FILE_WRITE_PATH

Haz los cambios siguientes:

JOB_NAME: un nombre de trabajo único que elijas
VERSION: la versión de la plantilla que quieres usar
Puedes usar los siguientes valores:
- latest para usar la última versión de la plantilla, que está disponible en la carpeta principal sin fecha del contenedor: gs://dataflow-templates-REGION_NAME/latest/
- el nombre de la versión, como 2023-09-12-00_RC00, para usar una versión específica de la plantilla, que se encuentra anidada en la carpeta principal correspondiente con la fecha en el bucket: gs://dataflow-templates-REGION_NAME/
Precaución: La última versión de las plantillas puede actualizarse con cambios importantes. Tus entornos de producción deben usar plantillas que se encuentren en la carpeta principal con fecha más reciente para evitar que estos cambios afecten a tus flujos de trabajo de producción.
REGION_NAME: la región en la que quieras desplegar tu trabajo de Dataflow. Por ejemplo, us-central1
PATH_TO_INPUT_TEXT_FILES: el patrón de los archivos de entrada en Cloud Storage
JAVASCRIPT_FUNCTION: el nombre de la función definida por el usuario (FDU) de JavaScript que quieras usar
Por ejemplo, si el código de tu función de JavaScript es myTransform(inJson) { /*...do stuff...*/ }, el nombre de la función es myTransform. Para ver ejemplos de UDFs de JavaScript, consulta Ejemplos de UDFs.
PATH_TO_JAVASCRIPT_UDF_FILE: el URI de Cloud Storage del archivo .js que define la función de JavaScript definida por el usuario (UDF) que quieres usar. Por ejemplo, gs://my-bucket/my-udfs/my_file.js
ERROR_FILE_WRITE_PATH: la ruta que quieras para el archivo de errores en Cloud Storage

API

Para ejecutar la plantilla mediante la API REST, envía una solicitud HTTP POST. Para obtener más información sobre la API y sus ámbitos de autorización, consulta projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates-LOCATION/VERSION/GCS_Text_to_Firestore
{
   "jobName": "JOB_NAME",
   "parameters": {
       "textReadPattern": "PATH_TO_INPUT_TEXT_FILES",
       "javascriptTextTransformGcsPath": "PATH_TO_JAVASCRIPT_UDF_FILE",
       "javascriptTextTransformFunctionName": "JAVASCRIPT_FUNCTION",
       "firestoreWriteProjectId": "PROJECT_ID",
       "errorWritePath": "ERROR_FILE_WRITE_PATH"
   },
   "environment": { "zone": "us-central1-f" }
}