Skip to main content

Usar la API de REST

Objetivos de aprendizaje

Después de completar esta unidad, podrá:
  • Iniciar sesión en la aplicación Postman y dirigirse a la carpeta REST en la recopilación de API de Salesforce.
  • Utilizar el recurso Describir SObject mediante GET.
  • Crear una cuenta con la API de REST.
  • Ejecutar una consulta con la API de REST.
Nota

Nota

¿Es su idioma de aprendizaje español (LATAM)? Los retos prácticos de Trailhead no están localizados en esta insignia. Asegúrese de cambiar el idioma de su Trailhead Playground a inglés y la configuración local a Estados Unidos. Siga las instrucciones que figuran aquí.

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.

Antes de continuar

Va a utilizar Postman para realizar algunas llamadas de API. Puede realizar solicitudes REST desde cualquier remitente HTTP. Y Postman es una de las muchas herramientas que puede utilizar para interactuar con su organización de Salesforce a través de la API.  

El primer paso es crear un nuevo Trailhead Playground, conectarlo a la aplicación Postman, configurar el uso compartido de recursos de origen cruzado y crear una bifurcación de la recopilación de API de Salesforce. Puede hacer esto si completa Inicio rápido: Conectar Postman a Salesforce

Puede realizar llamadas de API de REST a su Trailhead Playground con los recursos en la aplicación Postman de la carpeta REST de la recopilación de Salesforce, como haría con cualquier otra interfaz HTTP. Cuando selecciona un recurso de la recopilación de API de Salesforce, el URI se crea en la parte superior de la ventana principal. 

Describir el objeto de cuenta

Echemos un vistazo a cómo funciona.

Utilizará el recurso Describir SObject. Este recurso, en combinación con el método GET, devuelve metadatos de un objeto y sus campos. Vamos a describir el objeto Cuenta. 

  1. En Recopilaciones, seleccione la bifurcación de la Recopilación de API de Salesforce.
  2. Haga clic en la carpeta REST.
  3. Haga clic en SObject.
  4. Haga clic en SObject Describe mediante GET.
  5. En el panel principal, abra la ficha Parámetros.
  6. En Variables de rutas, en la fila SOBJECT_API_NAME, columna VALUE, ingrese Cuenta.

La ventana de solicitud de Postman muestra el URI de Describir SObject.


Antes de echar un vistazo a los resultados de la consulta, dediquemos un minuto a desglosar el URI de este recurso.

  • GET: método HTTP que se utiliza para esta llamada de API.
  • {{_Endpoint}}: lugar donde se realizará la solicitud. En este caso, agregó la URL de su Trailhead Playground al campo _endpoint en las variables para conectarse a Salesforce.
  • /services/data: especifica que realiza una solicitud de API de REST.
  • /v {{version}}: número de versión de API. Las comillas dobles indican que esto se puede establecer como variable.
  • /Sobjects: especifica que accederá a un recurso de la agrupación sObject.
  • /:SOBJECT_API_Name: sObject procesado; en este caso, Cuenta.
  • /describe: acción; en este caso, una solicitud de descripción.
     7. Haga clic en Guardar.
     8. Haga clic en Enviar.

La ventana de respuesta de Postman muestra los metadatos del objeto de cuenta.

¡Buen trabajo, capitán! Los metadatos de cuenta aparecen en la pantalla, y Postman proporcionó la respuesta en un formato bien presentado. Para ver la respuesta JSON sin procesar, haga clic en Sin procesar.

Los metadatos de cuenta se muestran en JSON. 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. 

  1. En la ventana de solicitud, haga clic en Encabezados.
  2. Agregue un nuevo encabezado con el valor de Key (Clave) Accept (Aceptar) y el valor application/xml.

Los encabezados de solicitud deben ser similares a este.

La ventana de solicitud de Postman muestra el campo de valor Encabezados establecido en application/xml.

     3. Haga clic en Enviar.

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. 

Para crear una cuenta:

  1. En REST, seleccione SObject y Crear SObject mediante POST.
  2. Abra la ficha Parámetros.
  3. En Variables de rutas, en la fila SOBJECT_API_NAME, columna VALUE, ingrese Cuenta.
  4. Abra la ficha Cuerpo.
  5. Sustituya el texto del cuerpo con este código:
{
"Name": "Captain Bly’s Finest Treasure Chests",
"ShippingCity": "Lisbon"
}

La ventana de solicitud de Postman muestra el URI de POST de SObject y el campo Cuerpo, los detalles de la cuenta que se crea.

6. Haga clic en Save (Guardar).
7. Haga clic en Enviar.

Ventana de respuesta de Postman que muestra el Id. de la cuenta creada.

Si success: true, la cuenta se ha creado con el Id. devuelto. 

Solo por curiosidad, vamos a crear una segunda cuenta sin especificar ningún nombre de cuenta. 

  1. Sustituya el texto del cuerpo de la solicitud por el siguiente texto.
{
"ShippingCity" : "Melbourne"
}

La ventana de solicitud de Postman muestra nuevos detalles de una nueva cuenta.

2. Haga clic en Enviar.

Oh, vaya. ¿Obtuvo la respuesta “Faltan los siguientes campos obligatorios: [Name]”? 

La ventana de respuesta de Postman muestra un error que indica que el campo Nombre falta en la solicitud.

Dado que Nombre es un campo obligatorio para la creación de una cuenta, el servidor no procesó la solicitud y se devolvió un error. Por suerte, toda la información necesaria para corregir la solicitud se incluye en la respuesta de error. Especifiquemos el nombre de cuenta: Pirate Pete’s Parrot Pellets, en el cuerpo de la solicitud. 

  1. Sustituya el texto del cuerpo de la solicitud por el siguiente texto.
{
"Name": "Pirate Pete's Parrot Pellets",
"ShippingCity": "Melbourne"
}

     2. Haga clic en Save (Guardar).
3. Haga clic en Enviar.

¡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 Melbourne. 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.

  1. En REST, seleccione Consulta de GET.
  2. Abra la ficha Parámetros.
  3. En Parámetros de consulta, en la fila q, la columna VALUE, pegue el siguiente texto.
SELECT Name From Account WHERE ShippingCity = 'Melbourne'

La ventana de solicitud de Postman muestra la ficha Parámetros donde el valor KEY q solicita los nombres de cuenta y la ciudad de envío es Melbourne.

4. Haga clic en Save (Guardar).
5. Haga clic en Enviar.

La consulta devuelve la cuenta que creó, Pirate Pete’s Parrot Pellets. ¡Buen trabajo, compañero!

Eche un vistazo a los atributos. Junto a “url” se incluye el URI de recurso de la cuenta devuelta. Su respuesta debe ser similar a la siguiente.

La ventana de respuesta de Postman muestra una cuenta devuelta donde la ciudad de envío es Melbourne. La cuenta es Pirate Pete’s Parrot Pellets.

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 pase de usar Postman a escribir código, usará el lenguaje de programación que prefiera para interactuar con la API de REST. 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 JSforce y Restforce, respectivamente.

Ejemplo de Node.js con JSforce

const jsforce = require("jsforce");const conn = new jsforce.Connection({
  // you can change loginUrl to connect to sandbox or prerelease env.
  // loginUrl : "https://test.salesforce.com"
});
// Log in with basic SOAP login (see documentation for other auth options)
conn.login(
  process.env.USERNAME,
  process.env.PASSWORD + process.env.SECURITY_TOKEN,
  (err, res) => {
    if (err) {
      return console.error("Failed to log in to Salesforce: ", err);
    }
    console.log("Successfully logged in!");
    // Run a SOQL query
    conn.query("SELECT Id, Name FROM Account LIMIT 5", (err, result) => {
      if (err) {
        return console.error("Failed to run SOQL query: ", err);
      }
      // Display query results
      const { records } = result;
      console.log(`Fetched ${records.length} records:`);
      records.forEach(record => {
        console.log(`- ${record.Name} (${record.Id})`);
      });
    });
  }
);

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
¡Siga aprendiendo gratis!
Regístrese para obtener una cuenta y continuar.
¿Qué hay para usted?
  • Consiga recomendaciones personalizadas para sus objetivos profesionales
  • Practique sus aptitudes con retos prácticos y pruebas
  • Siga y comparta su progreso con empleadores
  • Póngase en contacto para recibir asesoramiento y oportunidades laborales