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

Usar la API de REST

Objetivos de aprendizaje

Después de completar esta unidad, podrá:
  • Iniciar sesión en Workbench y navegar a REST Explorer.
  • Usar el recurso de descripción (describe).
  • Crear una cuenta con la API de REST.
  • Ejecutar una consulta con la API de REST.

Métodos y recursos de REST

¡Tierra a la vista! Hemos avistado la Isla de REST desde la proa, capitán. Antes de amarrar y empezar a usar la API, vamos a detenernos en los métodos y recursos de REST.

Un recurso de REST es una abstracción de determinada información o una acción, como un registro de datos único, una recopilación de registros o una consulta. Cada recurso de la API de REST se identifica mediante un identificador uniforme de recursos (URI) con nombre y el acceso se permite mediante métodos HTTP estándar (HEAD, GET, POST, PATCH, DELETE). La API de REST se basa en el uso de los recursos, sus URI y los vínculos entre ellos.

Puede usar un recurso para interactuar con su organización de Salesforce. Por ejemplo, puede hacer lo siguiente:
  • Recuperar información resumida de las versiones de API disponibles en su caso.
  • Obtener información detallada sobre un objeto de Salesforce, como un objeto de cuenta, usuario o personalizado.
  • Realizar una consulta o una búsqueda.
  • Actualizar o eliminar registros.

Una solicitud REST consta de cuatro componentes: un URI de recurso, un método HTTP, encabezados de solicitud y un cuerpo de solicitud. Los encabezados de la solicitud especifican los metadatos para la solicitud. El cuerpo de la solicitud especifica los datos para la solicitud si es necesario. En caso de no haber ningún dato que especificar, el cuerpo se omite en la solicitud.

Describir el objeto de cuenta

Ha llegado el momento de conocer la situación. Vamos a usar Workbench para realizar algunas llamadas de API. Workbench es un conjunto de herramientas que le permite interactuar con su organización de Salesforce mediante la API. Dado que puede generar solicitudes REST desde cualquier remitente HTTP, hay muchas otras herramientas disponibles para su uso (por ejemplo, consulte la información sobre cURL o Postman). Sin embargo, Workbench proporciona un marco sencillo y específico para las API de Salesforce y, por consiguiente, es la herramienta perfecta para investigar con el fin de prepararse para desarrollar una integración óptima.
El primer paso consiste en iniciar sesión en Workbench.
  1. Inicie sesión en su Trailhead Playground y navegue hasta Workbench.
  2. Para Environment (Entorno), seleccione Production (Producción).
  3. En el caso de la API, seleccione la última versión.
  4. Asegúrese de seleccionar I agree to the terms of service (Acepto las condiciones del servicio).
  5. Haga clic en Login with Salesforce (Iniciar sesión con Salesforce).

Ya está en la página de inicio de Workbench. Para este módulo, vamos a usar tan solo una de las muchas herramientas de Workbench, que este caso es REST Explorer.

En el menú superior, seleccione utilies (utilidades) | REST Explorer .

REST Explorer de Workbench

Puede realizar llamadas de API de REST en REST Explorer del mismo modo que lo haría en cualquier otra interfaz HTTP. El texto del cuadro de texto representa el URI de un recurso. Por una cuestión práctica, el dominio de nivel superior se ha omitido en el URI mostrado. Por ejemplo, el URI completo del recurso completado previamente en el cuadro de texto para el URI es https://foo.my.salesforce.com/services/data/v36.0.

Los botones de selección sobre el URI representan los métodos HTTP estándar. Para realizar una llamada de API, ingrese el URI del recurso, seleccione el método correspondiente, agregue encabezados si es necesario y haga clic en Execute (Ejecutar).

Hagamos una prueba con el recurso SObject Describe. Este recurso, en combinación con el método GET, devuelve metadatos de un objeto y sus campos.

Vamos a intentar describir el objeto de cuenta. Sustituya el texto existente en el cuadro de texto de URI por /services/data/vXX.0/sobjects/account/describe, donde XX se corresponde con la versión de la API que está utilizando.

URI para describir una cuenta
Dediquemos un minuto a desglosar el URI de este recurso.
  • /Services/data: especifica que estamos realizando una solicitud de API de REST.
  • /V36.0: es el número de versión de la API.
  • /Sobjects: especifica que vamos a acceder a un recurso de la agrupación de sObjects.
  • /Account: sObject procesado (en este caso, una cuenta).
  • /Describe: acción (en este caso, una solicitud de descripción).

Ahora, asegúrese de que el método GET se ha seleccionado y haga clic en Execute (Ejecutar).

Respuesta después de describir el objeto de cuenta

Buen trabajo, capitán. Los metadatos de cuenta se muestran en la pantalla. Además, Workbench ha aplicado un formato estupendo a la respuesta. Para ver la respuesta JSON sin procesar, haga clic en Show Raw Response (Mostrar respuesta sin procesar).

Respuesta JSON después de describir el objeto de cuenta

Los metadatos de cuenta se muestran como JSON debajo de algunos encabezados de respuesta HTTP. Dado que la API de REST es compatible con JSON y XML, vamos a cambiar el encabezado de la solicitud para especificar una respuesta XML. Junto a los métodos HTTP, haga clic en Headers (Encabezados). En el caso del valor de encabezado Accept, sustituya application/json por application/xml. Los encabezados de solicitud deben ser similares a este.

Encabezado de solicitud para especificar XML

Haga clic en Execute (Ejecutar). Se devuelve la respuesta XML sin procesar. ¡Excelente!

Crear una cuenta

A continuación, vamos a crear una cuenta con el recurso SObject y el método POST. En el cuadro de texto de URI, sustituya el texto existente con /services/data/vXX.0/sobjects/account, donde XX se corresponde con la versión de la API que está usando. Seleccione POST. Observe que se muestra un área de texto para el cuerpo de la solicitud, donde se deben especificar los valores de campo para la nueva cuenta. No obstante, primero vamos a cambiar el encabezado Accept de nuevo a JSON.

Haga clic en Headers (Encabezados). Cambie Accept: application/xml de nuevo a Accept: application/json. Su solicitud debe ser como la siguiente.

Encabezados de solicitud REST
En el cuerpo de la solicitud, ingrese el siguiente texto.
{
  "Name" : "NewAccount1",
  "ShippingCity" : "San Francisco"
}

Haga clic en Execute (Ejecutar). Verá una respuesta como la siguiente.

Respuesta de creación de cuenta correcta en la API de REST

Si success: true, la cuenta se ha creado con el Id. devuelto. Expanda la carpeta de errores para comprobar si hay errores.

Solo por curiosidad, vamos a crear una segunda cuenta sin especificar ningún nombre de cuenta. Sustituya el texto del cuerpo de la solicitud por el siguiente texto.
{
  "ShippingCity" : "San Francisco"
}

Haga clic en Execute (Ejecutar).

Oh, vaya. ¿Ha obtenido la respuesta REQUIRED_FIELD_MISSING? Expanda la carpeta REQUIRED_FIELD_MISSING (Falta el campo obligatorio) y, a continuación, expanda la carpeta fields (Campos). La respuesta expandida es como la siguiente.

Se obtiene un error cuando no se especifica ningún nombre de cuenta.
Dado que Name (Nombre) es un campo obligatorio para la creación de una cuenta, el servidor no ha procesado la solicitud y se devuelve un error. Por suerte, toda la información necesaria para corregir la solicitud se incluye en la respuesta de error. Vamos a especificar el nombre NewAccount2 y a cambiar la ciudad de envío en el cuerpo de la solicitud. Sustituya el texto del cuerpo de la solicitud por el siguiente texto.
{
  "Name" : "NewAccount2",
  "ShippingCity" : "New York"
}

Haga clic en Execute (Ejecutar). ¡Correcto!

Ejecutar una consulta

Ahora, supongamos que usted u otro usuario han creado cientos de cuentas. Desea buscar los nombres de todas las cuentas en las que la ciudad de envío es San Francisco. Puede usar el recurso Query para ejecutar una consulta SOQL y concentrarse en los registros exactos que desee, como si se tratara de un mapa del tesoro personalizado.

Sustituya el texto del cuadro de texto del URI por el siguiente texto: /services/data/v XX.0/query/?q=SELECT+Name+From+Account+WHERE+ShippingCity='San+Francisco', donde XX se corresponde con la versión de la API que está usando..

Hemos sustituido los espacios por el carácter + en la cadena de consulta para codificar el URI correctamente. Para obtener información sobre la codificación de direcciones URL con HTML, siga el vínculo correspondiente de la sección Recursos. Asegúrese de que el método GET se ha seleccionado y haga clic en Execute (Ejecutar).

Expanda la carpeta records (Registros). ¿Ve una carpeta con el nombre NewAccount1 de la primera cuenta que hemos creado? Estupendo. Haga clic en ella. A continuación, haga clic en la carpeta attributes (Atributos). Junto a url, se incluye el URI del recurso de la cuenta devuelta. Su respuesta debe ser similar a la siguiente.

La respuesta de la consulta devuelve un solo registro de cuenta.

Si desarrolla una integración, puede obtener este URI de la respuesta para acceder a más detalles sobre la cuenta.

Ejemplos de Node.js y Ruby

Ya tiene una idea excelente de las posibilidades que ofrece la API de REST. Por supuesto, cuando sale de Workbench para escribir código, interactúa con la API de REST mediante el lenguaje de programación elegido. Tenemos la suerte de que los desarrolladores expertos de Salesforce han desarrollado una serie de contenedores para varios lenguajes, lo que simplifica el proceso de consumo de la API de REST. A continuación, se incluyen dos consultas de ejemplo escritas con Node.js y Ruby en las que se usan los contenedores Nforce y Restforce respectivamente.

Ejemplo de Node.js con Nforce

var nforce = require('nforce');
// create the connection with the Salesforce connected app
var org = nforce.createConnection({
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET,
  redirectUri: process.env.CALLBACK_URL,
  mode: 'single'
});
// authenticate and return OAuth token
org.authenticate({
  username: process.env.USERNAME,
  password: process.env.PASSWORD+process.env.SECURITY_TOKEN
}, function(err, resp){
  if (!err) {
    console.log('Successfully logged in! Cached Token: ' + org.oauth.access_token);
    // execute the query
    org.query({ query: 'select id, name from account limit 5' }, function(err, resp){
      if(!err && resp.records) {
        // output the account names
        for (i=0; i<resp.records.length;i++) {
          console.log(resp.records[i].get('name'));
        }
      }
    });
  }
  if (err) console.log(err);
});

Ejemplo de Ruby con Restforce

require 'restforce'
# create the connection with the Salesforce connected app
client = Restforce.new :username => ENV['USERNAME'],
  :password       => ENV['PASSWORD'],
  :security_token => ENV['SECURITY_TOKEN'],
  :client_id      => ENV['CLIENT_ID'],
  :client_secret  => ENV['CLIENT_SECRET']
# execute the query
accounts = client.query("select id, name from account limit 5")
# output the account names
accounts.each do |account|
  p account.Name
end

Recursos

Guía del desarrollador de la API de REST

Primeros pasos con REST de Salesforce en Java

Referencia de codificación de URL de HTML

Sistema de traducción
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.