Usar la API de SOAP
Objetivos de aprendizaje
Después de completar esta unidad, podrá:
- Generar un archivo WSDL para su organización.
- Usar SoapUI para crear un proyecto de SOAP a partir del archivo WSDL.
- Iniciar sesión en su Trailhead Playground mediante la API de SOAP.
- Crear una cuenta con la API de SOAP.
Nota
¿Es su idioma de aprendizaje español (LATAM)? Comience el reto en un Trailhead Playground en español (LATAM) y utilice las traducciones entre paréntesis para navegar. Copie y pegue solo los valores en inglés, ya que las validaciones del reto dependen de los datos en ese idioma. Si no aprueba el reto en su organización en español (LATAM), recomendamos que (1) cambie la configuración local a Estados Unidos, (2) cambie el idioma a inglés (según estas instrucciones) y, luego, (3) haga clic en el botón “Check Challenge” (Comprobar el reto) nuevamente.
Consulte la insignia Trailhead en su idioma para obtener más información sobre cómo aprovechar la experiencia de Trailhead en otros idiomas.
WSDL para compañías y socios
Si ha navegado por los estrechos de alguna otra API basada en SOAP, ya sabe que el archivo WSDL (lenguaje de descripción de servicios web) es básicamente su mapa para comprender cómo se debe usar la API. Contiene los enlaces, protocolos y objetos necesarios para ejecutar llamadas de API.
Salesforce proporciona dos WSDL de API de SOAP para dos casos de uso distintos. El WSDL para compañías se ha optimizado para una única organización de Salesforce. Está tipificado de forma estricta y refleja la configuración específica de su organización, lo que significa que dos archivos WSDL para compañías generados en dos organizaciones distintas contienen información diferente.
El WSDL para socios se ha optimizado para su uso con varias organizaciones de Salesforce. Su tipificación es flexible y no cambia en función de la configuración específica de una organización. Normalmente, si va a desarrollar una integración para una sola organización de Salesforce, debe usar el WSDL para compañías. En el caso de varias organizaciones, use el WSDL para socios.
En esta unidad, vamos a usar el WSDL para compañías para explorar la API de SOAP. El primer paso es generar un archivo WSDL para su organización. En su Trailhead Playground, desde Setup (Configuración), ingrese API en el cuadro Quick Find (Búsqueda rápida) y, a continuación, seleccione API. En la página API WSDL, haga clic en Generar WSDL de compañía.
En la página Generar WSDL de compañía, haga clic en Generar. Cuando se genere el WSDL, haga clic con el botón secundario en la página y guarde el WSDL como un archivo XML en alguna ubicación de su computadora. Lo usaremos en breve.
La siguiente es una sugerencia para trabajar con el archivo WSDL para compañías. Dado que el WSDL para compañías refleja la configuración específica de su organización, siempre que realice un cambio en los metadatos de su organización, debe volver a generar el archivo WSDL. De este modo, el archivo WSDL no deja de estar sincronizado con la configuración de su organización.
Crear un proyecto de SOAP con SoapUI
Ahora que ya tenemos nuestro archivo WSDL, necesitamos un método para extraer la información y empezar a procesar solicitudes de API de SOAP. En el lenguaje del entorno web, este proceso se llama consumo de WSDL. Del mismo modo que un kraken devora un barco lleno de desventurados marineros, algunas herramientas como Web Services Connector (WSC) consumen el archivo WSDL. A continuación, las herramientas crean clases que le permiten procesar solicitudes con la API de SOAP mediante lenguajes de programación de uso frecuente.
En esta unidad, vamos a usar una herramienta de terceros llamada SoapUI para el consumo de nuestro archivo WSDL de compañía. SoapUI es una aplicación gratuita y de código abierto para probar los servicios web. Para empezar, descargue e instale SoapUI OpenSource desde el sitio web de SoapUI. Instale tan solo el componente SoapUI.
Asegúrese de que la versión de Java que SoapUI gestiona y utiliza es compatible con las políticas de seguridad de su organización. Puede encontrar la versión de Java que SoapUI utiliza seleccionando Help (Ayuda) | System Settings (Configuración del sistema) en SoapUI. Consulte www.soapui.org para obtener más información.
Después de instalar e iniciar SoapUI, en el menú File (Archivo), seleccione New SOAP Project (Nuevo proyecto de SOAP). Para nombre del proyecto, ingrese Exploring Salesforce SOAP API. En el caso del WSDL inicial, vaya a la ubicación en la que ha guardado el archivo WSDL de compañía y selecciónelo. No cambie ninguna otra opción. Su ventana de SoapUI debe ser similar a esta.
Haga clic en Aceptar. Después del procesamiento durante unos segundos, la carpeta Exploring Salesforce SOAP API (Exploración de la API de SOAP de Salesforce) se muestra en el panel del navegador en la parte izquierda de la pantalla. Debajo de esta carpeta, se incluye una entrada llamada SoapBinding que contiene varias operaciones.
¿Qué es lo que vemos aquí? Cada operación se corresponde con una solicitud de API de SOAP que podemos procesar. Las propiedades de cada operación se extraen de la información del archivo WSDL. Además, cada operación contiene una solicitud XML de ejemplo que incluye el extremo HTTPS de la operación y un mensaje de SOAP completado previamente.
Una cosa más: Salesforce requiere que todas las conexiones utilicen TLS 1.2 o versiones posteriores. Y si está utilizando SoapUI con Java 7, TLS 1.2 no está activado de forma predeterminada. Si intenta conectar con Salesforce con una versión antigua de TLS, recibirá un mensaje de error. Las buenas noticias es que la solución es bastante sencilla. Consulte esta útil publicación de blog para obtener más información.
Ya estamos preparados para empezar a procesar solicitudes de API de SOAP. ¡A toda vela, capitán!
Iniciar sesión en su Trailhead Playground
En SoapUI, desplácese hasta la operación login. Expándala y, a continuación, haga doble clic en Request 1 (Solicitud 1). Se muestra un ejemplo de solicitud de inicio de sesión de SOAP.
El siguiente es un breve desglose del URI del extremo (1).
- https://—Especifica HTTP segura.
- login.salesforce.com: es el dominio de nivel superior para una solicitud de inicio de sesión.
- /services/Soap especifica que estamos realizando una solicitud de API de SOAP.
- /c especifica que estamos usando el WSDL de compañía. Use /u para el WSDL de socio.
- /36.0 es el número de versión de la API. Falta el prefijo v porque algunas API lo incluyen antes del número de la versión y otras no. Este comportamiento es una de las peculiaridades de las API de Salesforce.
- /0DF36000000LHZw es el número de la versión del paquete.
Dado que no vamos a usar paquetes gestionados para este ejemplo, podemos eliminar el número de la versión del paquete del final del URI. Adelante, hágalo ahora.
El mensaje de SOAP (2) contiene todo lo que cabe esperar en un mensaje de SOAP: un sobre, un encabezado y un cuerpo.
Las propiedades incluidas en el elemento LoginScopeHeader están relacionadas con la autenticación de los usuarios de portales de clientes y autoservicio. Puesto que no es necesario detenernos en estos valores para nuestros fines, elimine el elemento <urn:LoginScopeHeader> completo (todo desde <urn: LoginScopeHeader> a </urn:LoginScopeHeader>). Resalte el texto en la ventana y pulse la tecla Supr.
A continuación, examine el elemento <urn:login> del cuerpo del mensaje. Este elemento es el meollo de la solicitud de inicio de sesión. Aquí especificamos nuestras credenciales de usuario. Sustituya los caracteres ? por su nombre de usuario y contraseña en su Trailhead Playground.
Para ello, necesitará sus credenciales de Trailhead Playground. Desde el Iniciador de aplicación, busque y abra Playground Starter y siga los pasos que aparecen a continuación. Si no ve la aplicación Playground Starter, consulte Buscar el nombre de usuario y la contraseña de su Trailhead Playground en la Ayuda de Salesforce.
- Haga clic en la ficha Obtener sus credenciales de inicio de sesión y anote su nombre de usuario.
- Haga clic en Restablecer mi contraseña. Esta acción envía un email a la dirección asociada con su nombre de usuario.
- Haga clic en el vínculo en el email.
Dado que va a enviar una solicitud de API desde una dirección IP desconocida a Salesforce, debe anexar su token de seguridad al final de su contraseña. Por ejemplo, si su contraseña es mypassword y su token de seguridad es XXXXXXXXXX, ingrese mypasswordXXXXXXXXXX en el elemento <urn:password>.
Haga clic en su avatar en la esquina superior derecha de la pantalla, seleccione Settings (Configuración) y elija Reset My Security Token (Restablecer mi token de seguridad) en My Personal Information (Mi información personal). Haga clic en Reset Security Token (Restablecer token de seguridad) para enviar un email a la dirección de email asociada con su Trailhead Playground con su token.
Su mensaje de SOAP debe ser similar al siguiente.
Haga clic en el botón de reproducción (triángulo verde) en la parte superior izquierda de la ventana de la solicitud. Este botón le permite enviar la solicitud y lanzar al mar su mensaje de SOAP en una botella. Esta es la apariencia que tiene cuando ampliamos la respuesta.
Felicitaciones, capitán. Ha iniciado sesión correctamente. La respuesta contiene información diversa sobre su organización y usuario. Sin embargo, lo más importante es que contiene el nombre de Mi dominio de su organización y un identificador de sesión que usaremos para futuras solicitudes, los cuales aparecen resaltados aquí.
Copie la instancia y el Id. de sesión en un archivo de texto. Los utilizaremos en un minuto.
Dado que es probable que la instancia de su organización cambie, no codifique las referencias a la instancia cuando empiece a desarrollar integraciones. En lugar de eso, use la URL de inicio de sesión de Mi dominio de su organización. Con Mi dominio, debe configurar un dominio específico de cliente para su organización de Salesforce. Mi dominio no solo elimina el inconveniente de cambiar los nombres de instancias, sino que también es útil para destacar su marca, aumentar la seguridad de su organización y personalizar su página de inicio de sesión.
Crear una cuenta
Al igual que hemos hecho con la API de REST, vamos a crear una cuenta con la API de SOAP. En el panel de navegación de la parte izquierda de la pantalla, busque la operación create. Expándala y haga doble clic en Request 1 (Solicitud 1).
Debido a que la creación de un registro es un proceso más complejo que el inicio de sesión, el mensaje create() de SOAP incluye muchos más elementos. La mayoría de los elementos se incluyen en el encabezado de la solicitud y son opcionales. Para simplificar el proceso, vamos a eliminar la mayor parte de la información del encabezado. No obstante, recuerde que las opciones que proporcionan estos encabezados están disponibles cuando crea un registro. Para obtener información acerca de la función de cada encabezado, consulte el tema dedicado a los encabezados SOAP de la guía del desarrollador de la API de SOAP.
Sin embargo, no deseamos eliminar el encabezado SessionHeader. Este encabezado va a contener el Id. de sesión obtenido de la respuesta de login(). Continúe y elimine los otros encabezados, desde <urn:EmailHeader> a </urn:AssignmentRuleHeader>. Su mensaje debe ser como el siguiente.
Obtenga el Id. de sesión que ha copiado en un archivo de texto y péguelo en la etiqueta <urn:sessionId> para sustituir el carácter ?.
Aún tenemos que hacer algunos ajustes en el cuerpo del mensaje. Primero, debemos especificar que vamos a crear una cuenta. Cambie el texto en la etiqueta <urn:sObjects> de modo que sea como este: <urn:sObjects xsi:type="urn1:Account" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> . Este ajuste especifica el tipo de registro correcto mediante la declaración del esquema de la instancia XML.
Además, queremos asignar un nombre a la cuenta. Agregue <Name>Sample SOAP Account</Name> en el elemento sObjects. Elimine además los elementos fieldsToNull e Id. Ahora, su mensaje debe ser similar al siguiente.
Hay una última acción que debemos realizar para poder procesar la solicitud. Cambie el extremo para especificar la instancia de su organización en lugar de login y elimine la versión del paquete del final del URI. El URI del extremo debe ser similar a este: https://NombreMiDominio.trailblaze.develop.my.salesforce.com/services/Soap/c/36.0.
Ya estamos listos para enviar la solicitud. Vuelva a hacer clic en el triángulo verde. ¡Funciona! Veamos la respuesta.
Observe LimitInfoHeader. Este encabezado devuelve información sobre el uso de la API. En el ejemplo anterior, se han realizado 9 de las 100.000 llamadas permitidas al día.
En el cuerpo de respuesta, observe el elemento <result>. <success>true</success> indica que el registro se creó con éxito. <id> incluye el Id. de registro, que puede utilizar en futuras solicitudes.
Estos son los fundamentos del procesamiento de solicitudes con la API de SOAP. Por supuesto, cada operación tiene sus propios parámetros y peculiaridades. Asegúrese de usar la guía del desarrollador de la API de SOAP como mapa cuando empiece a desarrollar integraciones con la API de SOAP.
Recursos
- Guía del desarrollador de la API de SOAP
- Hoja de referencia de API de SOAP
- Estructuras WSDL de muestra de API de SOAP
- Web Services Connector (WSC) de API de SOAP
- SoapUI Homepage