Empiece a realizar un seguimiento de su progreso
Inicio de Trailhead
Inicio de Trailhead

Usar la API masiva

Objetivos de aprendizaje

Después de completar esta unidad, podrá:
  • Describir las diferencias entre una solicitud asíncrona y una solicitud síncrona.
  • Crear un trabajo masivo con la herramienta REST Explorer en Workbench.
  • Importar datos en su organización de Salesforce mediante la adición de datos a un trabajo.
  • Monitorear el progreso de un trabajo.
  • Obtener los resultados de un trabajo.

API masiva y solicitudes asíncronas

La API masiva se basa en los principios de REST y se ha optimizado para trabajar con grandes conjuntos de datos. Puede usarla para insertar, actualizar, insertar y actualizar o eliminar muchos registros de forma asíncrona, lo que significa que puede enviar una solicitud y consultar los resultados posteriormente. Salesforce procesa la solicitud en segundo plano.

Por el contrario, la API de SOAP y la API de REST usan solicitudes síncronas y se han optimizado para aplicaciones cliente en tiempo real que actualizan unos cuantos registros a la vez. Estas dos API se pueden usar para procesar muchos registros, pero cuando los conjuntos de datos contienen cientos de miles de registros, dichas API son menos prácticas. El marco asíncrono de la API masiva se ha diseñado para garantizar el procesamiento de los datos de forma sencilla y eficiente con independencia de que se trate de unos cuantos miles o millones de registros.

La forma más sencilla de usar la API masiva es activarla para el procesamiento de registros en el Cargador de datos mediante archivos CSV. El uso del Cargador de datos elimina la necesidad de escribir su propia aplicación cliente. No obstante, en el caso de determinados requisitos únicos, puede ser necesario desarrollar una aplicación personalizada. La API masiva le permite hacerse con el timón del barco y dirigir el rumbo para encontrar la mejor solución en su caso.

Para esta unidad utilizará una versión más reciente de la API masiva denominada API masiva 2.0. Si desea aplicar las cosas que aprenda en esta unidad en la versión anterior de la API masiva, que aún es compatible, tendrá que utilizar URI de recursos diferentes, y crear y gestionar lotes así como trabajos. Para obtener más información sobre la versión anterior de la API masiva, consulte la Guía del desarrollador de API masiva.

Importar datos en la organización

Con el fin de explorar la API masiva, vamos a utilizar Workbench para crear algunos registros de cuenta.

Crear un trabajo masivo

Dado que la API masiva se basa en REST, podemos usar la herramienta REST Explorer de Workbench para procesar solicitudes de API masiva.
  1. Inicie sesión en su Trailhead Playground y navegue hasta Workbench.
  2. Para Environment (Entorno), seleccione Production (Producción). En el caso de la API, seleccione la última versión. Asegúrese de seleccionar I agree to the terms of service (Acepto las condiciones del servicio).
  3. Haga clic en Login with Salesforce (Iniciar sesión con Salesforce).
  4. En el menú superior, seleccione utilities (utilidades) | REST Explorer.

Ya estamos preparados para cargar nuestros datos. El primer paso es crear un trabajo. El trabajo especifica el tipo de operación y el objeto de datos con los que vamos a trabajar. Funciona como un depósito al que agregamos datos para su procesamiento.

Utilizaremos el recurso /jobs/ingest para crear un trabajo. Este recurso también puede utilizarse para obtener una lista de los trabajos vigentes.

Para crear un trabajo, enviamos una solicitud POST a /jobs/ingest con las propiedades del trabajo en el cuerpo de la solicitud. Dado que la API masiva se basa en REST, la solicitud adopta la forma ya familiar de una solicitud REST con cuatro componentes: URI, método HTTP, encabezados y cuerpo. El método es POST, como ya hemos mencionado.

En el caso del URI, sustituya el texto del cuadro de texto del URI por el siguiente texto: /services/data/v XX.0/jobs/ingest, donde XX.0 corresponde a la versión de API que está utilizando. Revisemos algunos detalles relacionados con este URI.
  • Estamos utilizando /services/data, que es el mismo extremo utilizado por la API de REST. La API masiva utiliza el mismo marco de trabajo que la API de REST, lo que significa que la API masiva admite muchas de las mismas funciones, como la autenticación de OAuth.
  • /jobs/ingest indica que estamos accediendo al recurso para crear trabajos de API masiva.
En el cuerpo de la solicitud, copie y pegue el siguiente texto.
{
  "operation" : "insert",
  "object" : "Account",
  "contentType" : "CSV",
  "lineEnding" : "CRLF"
}

Estas propiedades indican que deseamos usar la operación de inserción para los datos que enviemos al trabajo. Vamos a enviar datos de cuenta en formato CSV. La API masiva es compatible con cargas en CSV.

En REST Explorer, se debe mostrar información similar a la siguiente.

Crear una solicitud de trabajo en REST Explorer

Haga clic en Execute (Ejecutar) y compruebe la respuesta.

Generar respuesta del trabajo

La respuesta incluye todos los tipos de propiedades relacionadas con el trabajo, la mayoría de las cuales no son de utilidad para nosotros ahora, ya que aún no agregamos datos. No obstante, vamos a destacar algunas propiedades. Compruebe el Id. del trabajo (id) y cópielo en un archivo de texto. Lo utilizamos para agregar datos al trabajo y comprobar el estado del trabajo. Examine también la propiedad state. Cuando crea un trabajo, el estado se establece de inmediato en Open. Esto significa que está listo para empezar a recibir datos. Finalmente, consulte la propiedad contentUrl. Esta propiedad muestra la URL que utilizamos para cargar datos para el trabajo.

Agregar datos al trabajo

Ahora podemos insertar datos de cuenta en nuestro trabajo. Los datos para un trabajo se envían al servidor como un conjunto de registros en una solicitud PUT. El servidor procesa el conjunto de registros, determinando la manera óptima de cargar datos en Salesforce. Todo lo que tiene que hacer es cargar los datos.

Crear una nueva solicitud en Workbench. Sustituya el texto del cuadro de texto del URI por lo siguiente: /services/data/v XX.0/jobs/ingest/ jobID/batches. Sustituya jobID por el Id. de trabajo que ha copiado. Para el método HTTP, seleccione PUT.

Para este ejemplo, vamos a agregar un conjunto de registros con tan solo cuatro cuentas. Normalmente, la API masiva se usa para agregar miles o millones de registros, pero el principio es el mismo. Copie el siguiente texto en formato CSV en el cuerpo de la solicitud.
"Name"
"Sample Bulk API Account 1"
"Sample Bulk API Account 2"
"Sample Bulk API Account 3"
"Sample Bulk API Account 4"

Vamos a usar datos CSV porque es lo que hemos especificado al crear el trabajo.

Haga clic en Encabezados y cambie Content-Type a text/csv. Su solicitud debe ser similar a la siguiente.

Agregar datos empleando REST Explorer

Haga clic en Execute (Ejecutar).

La respuesta contiene solo un código de estado 201 (Creado), que indica que Salesforce recibió correctamente los datos del trabajo.

Cerrar el trabajo

Ahora que enviamos nuestros datos, tenemos que hacer saber a Salesforce que es el momento de procesar los datos. Haga esto cambiando el estado del trabajo de Open a UploadComplete.
Sustituya el texto del cuadro de texto del URI por lo siguiente: /services/data/v XX.0/jobs/ingest/ jobID . De nuevo, sustituya XX por la versión de la API que está usando y sustituya jobID por el Id. del trabajo. Para el método HTTP, seleccione PATCH. Haga clic en Encabezados y establezca Content-Type a application/json. En el cuerpo de la solicitud, sustituya el texto por el siguiente texto en formato JSON.
{
   "state" : "UploadComplete"
}

Haga clic en Execute (Ejecutar). La respuesta contiene información sobre el estado del trabajo. La propiedad state indica que estado del trabajo es UploadComplete. En este punto, Salesforce empieza a procesar el trabajo.

Comprobar el estado del trabajo

Enviamos nuestros datos. Hicimos saber a Salesforce que terminados de cargar datos. A continuación, el servidor debe procesar la solicitud. Podemos monitorear el progreso del servidor mediante la comprobación del estado del trabajo en la API o la interfaz de usuario de Salesforce. En Salesforce, desde Configuración, ingrese Trabajos de carga de datos masivos en el cuadro Búsqueda rápida y, a continuación, seleccione Trabajos de carga de datos masivos. Puede comprobar el estado de un trabajo en esta página. O bien, puede hacer clic en un Id. de trabajo para comprobar el estado y obtener resultados para dicho trabajo.

En la API, usamos el recurso /jobs/ingest/ jobID para monitorear un trabajo. Sustituya el texto del cuadro de texto del URI por lo siguiente: /services/data/v XX.0/jobs/ingest/ jobID , con las sustituciones habituales. Para el método HTTP, seleccione GET.

Haga clic en Execute (Ejecutar). Verá algo como esto.

Comprobar el estado del trabajo

Si su state es aún UploadComplete en vez de JobComplete, Salesforce aún está procesando el trabajo. No se preocupe, se procesará en unos minutos. Mientras tanto, puede deleitarse con una jarra de ron y probar con la misma solicitud cuando esté de vuelta. Si hay suerte su trabajo ya se procesó, puede recuperar los resultados del trabajo o hacer otro descanso para seguir disfrutando del ron.

Obtener los resultados del trabajo

Una vez un trabajo está en el estado JobComplete (o el estado Failed) podemos obtener información sobre los resultados en forma de registros procesados correctamente e incorrectamente.

Echemos un vistazo primero a los registros procesados correctamente. En REST Explorer de Workbench, sustituya el texto del cuadro de texto del URI por lo siguiente: /services/data/v XX.0/jobs/ingest/ jobID/successfulResults, con las sustituciones habituales. Para el método HTTP, seleccione GET.

Haga clic en Execute (Ejecutar). Verá algo como esto.

Compruebe los resultados correctos.

Salesforce devuelve un CSV que contiene una lista de todos los registros del trabajo que se procesaron correctamente. En este módulo creamos varios registros Cuenta. Los datos CSV contienen el Id. de registro del registro creado, y un valor de true para la columna sf__Created.

A veces algunos registros no pueden procesarse. Quizá el trabajo intentó crear registros Cuenta que ya existían. Quizá a los datos del trabajo les faltaban campos requeridos. En estos escenarios, podemos pedir a Salesforce una lista de los registros que tuvieron un error durante el procesamiento, junto con más información sobre lo que falló.

Volviendo a REST Explorer, sustituya el texto del cuadro de texto del URI por lo siguiente: /services/data/v XX.0/jobs/ingest/ jobID/failedResults, con las sustituciones habituales. Para el método HTTP, seleccione GET.

Haga clic en Execute (Ejecutar). Los resultados deben ser similares a los siguientes.

Compruebe los resultados incorrectos.

Salesforce proporciona un CSV que contiene una lista de los registros que encontraron errores durante el procesamiento, junto con el Id. del registro y el mensaje de error. En este caso, se insertaron todos sus registros correctamente, de modo que la lista de registros está vacía. ¡Excelente trabajo, capitán!

Recursos

Guía del desarrollador de la API masiva 2.0

Guía del desarrollador de API masiva (una versión anterior de la API masiva no tratada en esta unidad)

Workbench

Nota

Nota

Recuerde, este módulo está pensado para Salesforce Classic. Cuando inicie su organización para realizar prácticas, cambie a Salesforce Classic para completar este reto.