En 2021, anunciamos unplan para retirar las versiones heredadas de la API de la plataforma anualmente, de modo que nuestros equipos de ingeniería pudieran centrar sus esfuerzos de desarrollo en mejorar las últimas versiones de la API para mejorar la experiencia general de Salesforce al crear funciones personalizadas a través de aplicaciones. En esta publicación, compartiremos una actualización importante del plan de retiro de la API heredada, algunos consejos sobre cómo identificar el uso de la API heredada y cómo actualizar esas solicitudes de API.
Actualización importante del plan de jubilación de la API heredada
La última fase del plan de retiro de la API heredada se anunció a principios de 2022 y entró en vigencia durante el lanzamiento de Summer '22. Con esta versión, dejamos de usar las versiones SOAP, REST y Bulk API que van de la 21.0 a la 30.0. Como parte de nuestro plan original, estas versiones de API ya no serían compatibles, pero permanecerían disponibles hasta que las retiremos en la versión Summer '23.
Luego de consultar con la comunidad y nuestros socios, decidimos retrasar el próximo retiro de la API al lanzamiento de Summer '25 para garantizar una transición sin problemas (consulte el artículo de conocimientos ). Debido a esta extensión, las versiones de API 21.0 a 30.0 aún no son compatibles, pero seguirán estando disponibles hasta el lanzamiento de Summer '25.
Desde Summer '21 , cada vez que realiza una llamada a una API heredada con REST o Bulk API, verá un encabezado Warning en la respuesta con un mensaje que describe el problema como este:
Una vez que las versiones heredadas de la API se retiren en Summer '25, las solicitudes a esas versiones fallarán con los siguientes errores:
- La API REST devolverá el estado HTTP
410: GONE
- La API SOAP devolverá el estado HTTP
500: UNSUPPORTED_API_VERSION
- La API masiva devolverá el estado HTTP
400: InvalidVersion
Ahora que conoce el último plan, veamos cómo puede identificar si se ve afectado y cómo.
Identificar el uso de la API heredada
Puede verificar las llamadas API heredadas usted mismo en cualquier momento, y hay varias formas de hacerlo.
Todas las transacciones de la API de Salesforce se registran en los registros de Monitoreo de eventos. El monitoreo de eventos normalmente requiere una licencia específica, pero hemos expuesto el evento Uso total de la API ( ApiTotalUsage ) a todos los clientes de forma gratuita, para que pueda monitorear el consumo de la API heredada e identificar los clientes y las integraciones que deben actualizarse. Las organizaciones habilitadas para API tienen acceso gratuito a los archivos de registro de eventos de uso total de API con retención de datos de 1 día. Con el Monitoreo de eventos habilitado, puede acceder a este y a todos los demás tipos de archivos de registro de eventos con una retención de datos de 30 días.
Los registros contienen campos clave que guían sus investigaciones:
- Los clientes proporcionan
CLIENT_NAME opcionalmente, pero es especialmente útil para identificar aplicaciones e integraciones que realizan llamadas API que requieren investigación y ajustes. Compartiremos más sobre este campo en la última sección de esta publicación.
-
CONNECTED_APP_ID le dice qué aplicación conectada está en el origen de las llamadas a la API.
-
USER_ID y CLIENT_IP son útiles para identificar el origen de las llamadas API heredadas, pero existe la posibilidad de que estos valores se compartan entre varias aplicaciones en caso de que se realice una cuenta técnica de usuario/sistema (ID de usuario compartido) o llamadas desde una ubicación de oficina física ( dirección IP compartida). Compartiremos cómo usar la nueva licencia de usuario de integración para abordar los problemas de usuarios compartidos en la última sección de esta publicación.
- Los campos
API_FAMILY , API_VERSION , API_RESOURCE , URI y HTTP_METHOD le brindan pistas valiosas sobre el tipo de operaciones que realizan los clientes API.
Compartimos varias herramientas para acceder a los registros en nuestra publicación anterior , y también puede usar herramientas de terceros para automatizar esta tarea. Compartiremos una opción adicional que puede ser relevante para los usuarios preocupados por ejecutar código de terceros con acceso API a su organización.
Uso de Postman para identificar el uso de la API heredada
Puede utilizar la colección Postman de las API de la plataforma de Salesforce para inspeccionar sus registros de Salesforce con estos pasos:
- Configure la colección Postman y autentíquese en su organización .
- Enumere los archivos de registro que rastrean el acceso a la API:
- Seleccione REST > Solicitud de consulta .
- Reemplace el valor del parámetro de consulta
q con la siguiente consulta SOQL: SELECT LogFile, EventType, CreatedDate FROM EventLogFile WHERE EventType IN ('API', 'RestApi', 'BulkApi', 'ApiTotalUsage')
- Haz clic en Enviar.
- Recupere los ID del archivo de registro de la respuesta.
- Para cada archivo de registro devuelto en el paso anterior, recupere y escanee el contenido del registro:
- Seleccione REST > Registros > Obtener solicitud de archivo de registro de eventos .
- Establezca el ID del archivo de registro en el valor de la variable de ruta
id .
- Haz clic en Enviar.
- Lea el contenido del archivo de registro en la respuesta. Puede moverse a la pestaña Respuesta sin procesar y guardarla como un archivo CSV o usar la pestaña Visualizar para obtener una vista previa del contenido directamente en Postman.
- Mire la columna URI o API_VERSION y verifique las versiones de API heredadas (versiones 30.0 y anteriores).
Después de identificar que está llamando a versiones de API heredadas, el siguiente paso es actualizar estas dependencias a versiones de API heredadas.
Actualizar dependencias a versiones de API heredadas
El procedimiento de actualización depende del tipo de API que esté utilizando, pero aquí hay una breve descripción general de lo que se requiere:
- Para llamadas API basadas en SOAP, genere un nuevo WSDL e incorpórelo a la integración afectada
- Para puntos finales REST, actualice el número de versión en el URI a la versión principal actual
- Aunque puede actualizar de manera similar los URI para puntos finales
/async en el caso de Bulk API, la forma más gratificante de actualizar las llamadas heredadas es adoptar Bulk API 2.0 y disfrutar del flujo de trabajo más simple y los límites mejorados.
Tenga en cuenta que las aplicaciones (p. ej., el cargador de datos) y los paquetes también pueden estar realizando llamadas API heredadas debido a bibliotecas obsoletas (conectores de servicios web, kit de herramientas AJAX, interfaz COM SForceOfficeToolkit o kit de herramientas Force.com para PHP, solo por nombrar algunos) . Asegúrate de actualizarlos también.
Y recuerda: no importa el cambio, asegúrate de realizar pruebas de regresión para asegurarte de que todo funciona como se esperaba.
Preparándonos para el futuro
Ya sea que se haya visto afectado por el plan de jubilación heredado o no, debe planificar el futuro retiro de la versión API. Le dejaremos algunas prácticas recomendadas para el gobierno de API.
Aproveche las licencias de usuario de la integración de Salesforce
En Spring '23, presentamos un nuevo tipo de licencia dedicado a las integraciones: la licencia de usuario de Integración de Salesforce . Esta nueva licencia se basa en el principio de acceso con privilegios mínimos y le permite crear usuarios solo de API para integraciones de sistema a sistema con derechos de acceso específicos. La principal ventaja de este nuevo tipo de licencia es la seguridad, pero también permite un mejor seguimiento de las acciones de integración, ya que podrá asignar distintos usuarios solo de API a la integración y relacionar las llamadas de API de integración con ID de usuario específicas en sus registros.
Se incluyen cinco licencias de usuario de Integración de Salesforce en cada organización Enterprise, Unlimited y Performance Edition. También puede comunicarse con su ejecutivo de cuenta si necesita más.
Especifique un nombre de cliente al crear integraciones de API REST
Al crear nuevas integraciones con la API REST, asegúrese de especificar un nombre de cliente utilizando el encabezado de solicitud Sforce-Call-Options de la siguiente manera:
Sforce-Call-Options: client=myClientName
El nombre del cliente que especifique en el encabezado estará visible en los registros en el campo CLIENT_NAME . Esto le ayuda a depurar y auditar las llamadas a la API de integración.
palabras de cierre
Esperamos que este retraso adicional en nuestro plan de retiro de API heredado permita una transición sin problemas, y lo alentamos a que comience hoy, independientemente de la nueva fecha límite. Migrar a versiones de API más nuevas siempre es una apuesta segura para obtener acceso a nuevas capacidades y mejorar el rendimiento y la seguridad.
Sobre el Autor
Philippe Ozil es un defensor principal de desarrolladores en Salesforce, donde se enfoca en la plataforma de Salesforce. Escribe contenido técnico y habla con frecuencia en conferencias. Es un desarrollador full-stack y disfruta trabajar en proyectos DevOps, robótica y VR. Sígalo en Twitter @PhilippeOzil o consulte sus proyectos de GitHub @pozil .
