Ask me anything
How can I help you with Catalyst today?
Bulk Write de registros
La operación Bulk Write puede obtener miles de registros desde un archivo CSV cargado en un bucket en Stratus e insertarlos en una tabla específica en el Data Store. Esta operación de gran volumen de datos puede realizarse en una sola ejecución de API.
Después de que la operación de escritura masiva se haya ejecutado exitosamente, se generará un archivo de informe CSV que contiene los detalles de la ejecución del trabajo en una URL de descarga.
Catalyst admite tres APIs para la operación de escritura masiva: una API Create Bulk Write, una API Check Bulk Write Status para verificar el estado de la ejecución del trabajo manualmente, y una API Download Bulk Write Result para descargar los resultados. También puedes configurar una URL de callback para habilitar la publicación automática de las respuestas de estado del trabajo en ella.
Crear un trabajo de Bulk Write
Descripción
Esta API activa la operación de escritura masiva para obtener los registros de un archivo CSV almacenado en Stratus y exportarlos a una tabla en el Data Store, según los criterios que especifiques en el JSON de entrada. El archivo CSV se referencia usando su Object URL en Stratus, y la tabla se referencia usando su ID único de tabla o el nombre de la tabla.
Nota:
-
Asegúrate de haber cargado el archivo CSV requerido en Stratus antes de comenzar a ejecutar esta operación.
-
La primera fila del archivo CSV debe ser la fila de encabezado, es decir, los nombres de las columnas deben estar presentes como fila de encabezado.
-
El archivo CSV debe contener datos en el formato que se adhiere a los estándares de archivos CSV. Si el archivo no tiene el formato estándar, los datos escritos en la tabla podrían estar corruptos.
-
Puedes insertar 5000 registros en cada tabla por proyecto en el entorno de desarrollo usando esta API. Si el archivo CSV contiene más registros que esa cantidad, los primeros 5000 registros se escribirán en la tabla. Los demás se omitirán en el entorno de desarrollo. No hay límites de tabla para la inserción en el entorno de producción. Sin embargo, la API Bulk Write puede insertar hasta 100000 registros en una sola llamada API desde un archivo CSV incluso en el entorno de producción. Si necesitas escribir más registros, puedes hacerlo en lotes de 100000 registros enviando múltiples solicitudes de la API Bulk Write en consecuencia.
Hay tres operaciones que se pueden realizar usando esta API:
- Insert: Inserta nuevas filas de datos en la tabla desde el archivo CSV
- Update: Actualiza filas de datos existentes en la tabla. Los registros se identifican ya sea usando una columna única en la tabla, o usando sus ROWIDs generados en el Data Store.
- Upsert: Habilita las operaciones de inserción y actualización al mismo tiempo. Si el registro ya existe, la fila se actualiza. Si el registro no existe, se inserta una nueva fila con los datos.
Detalles de la solicitud
URL de solicitud
{api-domain}/baas/v1/project/{projectId}/bulk/write
Encabezados de solicitud
Authorization: Zoho-oauthtoken {oauth_token}
Encabezados opcionales
CATALYST-ORG: {org_id}
Environment: Development
Scope
ZohoCatalyst.tables.bulk.CREATE
Propiedades JSON de la solicitud
La entrada para la solicitud de la API Bulk Write debe enviarse en formato JSON. Los parámetros de la solicitud se explican a continuación.
Especifica la operación a ejecutar usando la API.
Valores permitidos: insert, update, upsert
Operación predeterminada: insert
La columna única usando la cual se identifican los registros.
Por ejemplo, si especificas una columna única llamada ‘EmployeeID’ como el valor de find_by, Catalyst buscará los registros en la tabla del Data Store usando el valor de EmployeeID. Para la operación update, Catalyst actualizará las filas que coincidan con el EmployeeID del archivo CSV. Para la operación upsert, Catalyst actualizará las filas existentes e insertará nuevas filas si no hay registros con valores de EmployeeID coincidentes.
Update: Puede ser una columna con valores únicos según la configuración en el Data Store, o el ROWID generado por Catalyst para los registros.
Upsert: Solo puedes especificar una columna con valores únicos según la configuración en el Data Store. No podrás especificar el ROWID como valor de find_by. Esto se debe a que upsert insertará nuevas filas si no se encuentran coincidencias, y los valores de ROWID no estarán disponibles para filas que no existen en el Data Store.
Insert: Si especificas una columna find_by para una operación insert, cualquier registro que coincida con los valores de la columna del archivo CSV se omitirá y no se insertará en la tabla del Data Store. Esto se debe a que insert no puede actualizar si un registro dado ya existe.
Mapeo de clave foránea para las columnas que son claves primarias en otras tablas. Esto se especifica si alguna columna importada desde el archivo CSV debe configurarse como clave foránea.
Debes mapear las claves foráneas en el siguiente formato:
{
“local_column” : “local_column_name_1”,
“reference_column” : “reference_column_name_1”
}
donde local_column es el nombre de la columna en la tabla donde se procesa la operación de escritura masiva, y reference_column es el nombre de la columna en la tabla en la que es una clave primaria.
Consulta el código de solicitud de ejemplo.
La sección donde puedes definir las propiedades de la URL de callback, donde se enviarán las respuestas JSON automáticas de los estados del trabajo.
La URL donde se enviarán las respuestas automáticas usando el método HTTP POST, cada vez que el estado del trabajo cambie. La información sobre los detalles del trabajo estará contenida en el cuerpo de la respuesta JSON.
Si no configuras una URL de callback, debes verificar manualmente el estado del procesamiento del trabajo cuando lo necesites, usando la API Check Bulk Write Status.
Encabezados que necesitas que se pasen en la respuesta JSON a la URL de callback
Debes especificar los encabezados como:
{
"{header_name_1}" : “{header_value_1}”,
"{header_name_2}" : “{header_value_2}”
}
y así sucesivamente. Consulta el código de solicitud de ejemplo.
Parámetros que necesitas que se agreguen a la URL de callback
Debes especificar los parámetros como:
{
"{param_name_1}" : “{param_value_1}”,
"{param_name_2}" : “{param_value_2}”
}
y así sucesivamente. Consulta el código de solicitud de ejemplo.
Detalles de la respuesta
Hay tres estados de procesamiento del trabajo que generarán tres respuestas diferentes:
-
In-Progress: Cuando ejecutas la API, Catalyst te enviará inmediata y automáticamente una respuesta indicando que la ejecución del trabajo está en progreso. Si has configurado una URL de callback en la solicitud, la respuesta también se publicará en la URL en el formato que definiste.
La respuesta contendrá un parámetro job_id que puedes usar para verificar el estado de la ejecución del trabajo para respuestas posteriores, si no has configurado una URL de callback.
-
Success: La respuesta del estado exitoso contendrá una URL de descarga, donde puedes descargar un archivo de informe CSV que contiene los detalles de la ejecución del trabajo. Listará todos los registros que fueron omitidos de la escritura junto con las razones. Si no has configurado una URL de callback, esta respuesta no será enviada por Catalyst automáticamente.
-
Failed: La respuesta del estado fallido contendrá una descripción del error que ocurrió y los detalles. Si no has configurado una URL de callback, esta respuesta no será enviada por Catalyst automáticamente.
curl -X POST https://api.catalyst.zoho.com/baas/v1/project/4000000006007/bulk/write
-H “Authorization: Zoho-oauthtoken 1000.91016.2f*57”
-d ‘{
“table_identifier”: “3376000000165511”,
“operation”: “insert”,
“object_details”: {
“bucket_name”: “zylker-emp”,
“object_key”: “employees/emp_rec.csv”,
“version_id”: “3546576879809”
},
“callback”: {
“url”: “https://hr.zylker.com/es/EmpRecords/_callback.php",
“headers”: {
“src”: “ZCatalyst”,
“operation”: “bulkwriteAPI”
},
“params”: {
“project_name”: “EmployeeDatabase”
}
},
“find_by”: “EmpID”,
“fk_mapping”: [
{
“local_column”: “EmployeeID”,
“reference_column”: “EmpID”
},
{
“local_column”: “DepartmentID”,
“reference_column”: “DeptID”
}
]
}’
{
"status": "success",
"data": {
"job_id": 2000000110044,
"status": "In-Progress",
"operation": "insert",
"project_details": {
"project_name": "ShipmentTracking",
"id": 4000000006007
},
"query": [
{
"table_id": 3376000000165511,
"object_details": {
"bucket_name": "zylker-emp",
"object_key" : "employees/emp_rec.csv",
"version_id":"3546576879809"
}
}
],
"callback": {
"url": "https://hr.zylker.com/es/EmpRecords/_callback.php",
"headers": {
"src": "ZCatalyst",
"operation": "bulkwriteAPI"
},
"params": {
"project_name": "EmployeeDatabase"
}
},
"created_by": {
"zuid": 3000000006111,
"is_confirmed": true,
"email_id": "emma@zylker.com",
"first_name": "Amelia",
"last_name": "Burrows",
"user_id": 671930409
},
"created_time": "Oct 05, 2020 07:33 PM"
}
}
{
"status": "success",
"data": {
"job_id": 2000000110044,
"status": "Completed",
"operation": "insert",
"project_details": {
"project_name": "ShipmentTracking",
"id": 4000000006007
},
"query": [
{
"table_id": 3376000000165511,
"details": {
"object_url" : "https://zylker-emp-development.zohostratus.com/employees/emp_rec.csv"
}
}
],
"callback": {
"url": "https://hr.zylker.com/es/EmpRecords/_callback.php",
"headers": {
"src": "ZCatalyst",
"operation": "bulkwriteAPI"
},
"params": {
"project_name": "EmployeeDatabase"
}
},
"created_by": {
"zuid": 3000000006111,
"is_confirmed": true,
"email_id": "emma@zylker.com",
"first_name": "Amelia",
"last_name": "Burrows",
"user_id": 671930409
},
"created_time": "Oct 05, 2020 07:25 PM",
"results": {
"download_url": "https://api.catalyst.zoho.com/baas/v1/bulk/write/2000000110013/download",
"description": "Bulk WRITE job completed. ",
"details": [
{
"table_id": 3376000000165511,
"records_processed": 176
}
]
}
}
}
{
"status": "success",
"data": {
"job_id": 2000000110044,
"status": "Failed",
"operation": "insert",
"project_details": {
"project_name": "ShipmentTracking",
"id": 4000000006007
},
"query": [
{
"table_id": 3376000000165511,
"details": {
"object_url" : "https://zylker-emp-development.zohostratus.com/employees/emp_rec.csv"
}
}
],
"callback": {
"url": "https://hr.zylker.com/es/EmpRecords/_callback.php",
"headers": {
"src": "ZCatalyst",
"operation": "bulkwriteAPI"
},
"params": {
"project_name": "EmployeeDatabase"
}
}
"created_by": {
"zuid": 3000000006111,
"is_confirmed": true,
"email_id": "emma@zylker.com",
"first_name": "Amelia",
"last_name": "Burrows",
"user_id": 671930409
},
"created_time": "Oct 05, 2020 07:25 PM",
"results": {
"description": "The reference_column 'DeptID' in fk_mapping of table 3376000000165511 is not a unique column",
"details": [ ]
}
}
}
Yes
No
Thank you for your feedback!
Send your feedback to us