Ritiro delle versioni API dalla 21.0 alla 30.0 di Salesforce Platform

Data di pubblicazione originale - 20 ottobre 2020

Aggiornato - 4 maggio 2024
 

Qual è lo stato delle versioni dalla 21 alla 30 delle API SOAP, REST e in blocco?

• Stato attuale: queste versioni API sono dichiarate obsolete (a partire dal rilascio Summer ‘22) e non sono più supportate. Sebbene sia possibile continuare a utilizzarle, se si verificano dei problemi che comportano la registrazione di un caso con l'Assistenza Salesforce, sarà necessario innanzitutto aggiornare la versione API. Non verrà fornito alcun supporto tecnico, né correzioni di bug per queste versioni API legacy.

• Stato futuro: rilascio Summer ‘25 – queste versioni API saranno ritirate. Le applicazioni che utilizzano tali versioni subiranno delle interruzioni perché le chiamate falliscono e rispondono con un errore indicante che non è possibile trovare l'endpoint richiesto e che la piattaforma non è in grado di elaborare tale endpoint. Gli errori sono elencati di seguito:

  • L'API REST restituisce 410: GONE.

  • L'API SOAP restituisce 500: UNSUPPORTED_API_VERSION.

  • L'API in blocco (Bulk) restituisce 400: InvalidVersion.

Nota: le versioni API dalla 7.0 alla 20.0 erano state già ritirate e rese non disponibili durante il rilascio Summer ‘22.

Perché stiamo ritirando queste versioni API?
Stiamo concentrando i nostri sforzi di sviluppo sull'ottimizzazione delle ultime versioni delle API con l'obiettivo di migliorare l'esperienza Salesforce complessiva a livello di creazione di funzionalità personalizzate attraverso le applicazioni. A titolo di confronto, la versione API 30 risaliva al rilascio Spring ‘14.

Su quali elementi avrà effetto il ritiro di queste versioni API?
Questo ritiro interessa qualsiasi codice, pacchetto, applicazione o integrazione che esegue una richiesta di versioni dalla 21.0 alla 30.0 delle API SOAP, REST o in blocco.  

Nota: questo ritiro non ha effetto sugli elementi elencati di seguito:

• Le versioni API delle classi Apex, dei trigger Apex, delle pagine Visualforce, dei flussi e di Process Builder

• Il prodotto pronto all'uso B2B Classic/Visualforce

• Componenti dei metadati con versione in un pacchetto gestito

• Servizi Web Apex REST & SOAP personalizzati (un servizio Web Apex personalizzato permette di rendere chiamabile un metodo della classe Apex come un'API pubblica. Ulteriori informazioni sui servizi Web Apex sono disponibili qui: Servizi Web Apex) 

Quali azioni devo intraprendere?

1. Identificare i componenti/le applicazioni all'interno dell'organizzazione che utilizzano queste versioni API legacy.

2. Aggiornare tali componenti/applicazioni. Prima del rilascio Summer ‘25, è necessario modificare o aggiornare le proprie applicazioni in modo che funzionino con le versioni API supportate attuali. Salesforce raccomanda vivamente di passare a versioni più nuove delle API, che offrono funzionalità avanzate e livelli di sicurezza e prestazioni migliorati.

Consultare la tabella seguente per ottenere informazioni su alcuni degli elementi più comuni interessati e sulle azioni da intraprendere per ciascun elemento:

Come faccio a sapere se/dove vengono usate queste versioni API obsolete nelle mie applicazioni?

Contattare gli sviluppatori delle applicazioni in uso per determinare le versioni API.

Inoltre è possibile esaminare gli eventi API nell' EventLogFile Utilizzo totale API che contiene il rapporto sulle attività API SOAP, REST e in blocco da Salesforce tramite uno dei seguenti due metodi.

1. Il primo metodo consiste nell'utilizzare il nuovo Browser file registro eventi incluso nel rilascio Summer ‘24.  Con questo strumento è possibile sfogliare i file del registro eventi Utilizzo totale API nella propria organizzazione e scaricarli come file CSV per visualizzare i singoli eventi API.  

Da Imposta, passare a Sicurezza → Monitoraggio evento → Browser file registro eventi.  Qui è possibile visualizzare i file registro eventi delle ultime 24 ore (o degli ultimi 30 giorni se è stato attivato Monitoraggio evento).  Successivamente si possono scaricare i singoli file del registro eventi come file CSV per visualizzarne gli eventi API.

2. Il secondo metodo consiste nell'utilizzare un client quale Salesforce CLI per eseguire una query SOQL rispetto all'oggetto EventLogFile. Questo fornisce i file del registro eventi delle ultime 24 ore (o degli ultimi 30 giorni se è stato attivato Monitoraggio evento).

sf data query -q "SELECT Id, LogFile, EventType, CreatedDate FROM EventLogFile WHERE EventType IN ('ApiTotalUsage')" -o <nome utente>

Per ciascun risultato, eseguire una richiesta API REST utilizzando gli endpoint nel risultato della query per recuperare i dati del registro eventi in quel file del registro eventi.*

/services/data/v58.0/sobjects/EventLogFile/0AT3i000005vXpWGAU/LogFile

Incollare il corpo della risposta in un'applicazione per visualizzare facilmente i dati del registro eventi come file CSV.

3. Esaminare tutti i file CSV e stabilire se vengono effettuate richieste a endpoint con le API versione 30 o precedenti.

Esaminare tutti gli eventi di Utilizzo totale API (ApiTotalUsage EventType) con API_VERSION 30 e precedenti**

4. Per eventuali integrazioni o client che utilizzano la versione 30.0 e versioni precedenti, seguire i suggerimenti forniti dai campi chiave nei dati del registro eventi come ausilio per individuare l'origine della chiamata API legacy:

CLIENT_NAME, CONNECTED_APP_ID, ENTITY_NAME, USER_ID

Per ulteriori informazioni su Monitoraggio evento, seguire il modulo Trailhead Event Monitoring.

*Per le informazioni preliminari sull'esecuzione di una richiesta API REST, vedere questo Trailhead Use REST API (Utilizzo dell'API REST).

**Il tipo di evento "Utilizzo totale API" raggruppa le informazioni sulle richieste pertinenti tra le varie API SOAP, REST e in blocco, incluse le informazioni sulle versioni. Vedere i dettagli sulla definizione di evento qui. Le organizzazioni abilitate per le API hanno accesso libero ai file del registro eventi Utilizzo totale API con conservazione di 1 giorno di dati. Con Monitoraggio evento abilitato, è possibile accedere a questo e a tutti gli altri tipi di file del registro eventi con conservazione di 30 giorni di dati.

Inoltre, per trovare le richieste API in blocco o gli accessi API SOAP, si può procedere come segue:

• Per trovare le richieste API in blocco: per l'API in blocco, passare alla pagina "Processi di caricamento dati in blocco" all'interno di Imposta e visualizzare i dettagli di ciascun processo "Bulk V1". Eventuali processi con un valore uguale o inferiore a 30.0 all'interno del campo "Versione API" saranno interessati da questo ritiro delle API.

• Per trovare gli accessi API SOAP: per l' operazione di login() SOAP, passare a "Cronologia accessi" in Imposta ed esaminare le voci con "SOAP Enterprise" o "SOAP Partner" come Tipo API. In alternativa, è possibile interrogare l'sObject LoginHistory tramite SOQL. Eventuali voci di accesso con un valore uguale o inferiore a 30.0 all'interno del campo "Versione API" saranno interessati da questo ritiro.

Nota: I partner possono sfruttare i Registri di utilizzo pacchetti per approfondimenti sull'utilizzo delle API obsolete.

Come posso ottenere altre informazioni?

Per i dettagli sulle versioni API più recenti supportate, visitare il sito Developers per gli sviluppatori Salesforce.

Per i dettagli sulle API e la messaggistica in uscita:

• Platform API Basics (Nozioni fondamentali sulle API della piattaforma) (Trailhead)

• Introduction to SOAP API (Presentazione dell'API SOAP) (Developer Guide)

• Understanding Outbound Messaging (Informazioni sulla messaggistica in uscita) (Developer Guide)

• Bulk API (API in blocco) (Developer Guide)

• Introduction to REST API (Presentazione dell'API REST) (Developer Guide)

  • "REST" copre tutte le API con URI degli endpoint sotto /services/data/vXX.Y/ and /services/metadata/vXX.Y/ dove XX.Y è la versione dell'API. Questo include l' API REST Salesforce Platform "standard" per il funzionamento con gli sObjects e i record, ma anche le seguenti risorse:

    • Metadata API Developer

    • Tooling API

    • API Chatter/Connect

    • API Query e Query All

    • API ricerca

    • API limiti

    • API accesso (nota anche come "Identity")

• • • Osservare i risultati di una richiesta REST a GET /services/data/v30.0 or GET /services/metadata/v30.0 per capire le risorse di livello più elevato interessate quando verranno ritirati gli endpoint versione v30.0 e precedenti.

Se si desiderano maggiori informazioni sul ritiro di queste API legacy, è possibile leggere l'articolo del blog An Important Update to Our Legacy API Retirement Plan (Un aggiornamento importante al nostro piano di ritiro delle API legacy).

Per una spiegazione delle versioni API rivolta agli amministratori, ascoltare il podcast qui (è di qualche anno fa, ma le informazioni principali sono ancora valide): Why API Versions Matter with Kris Harrison (Perché le versioni API sono importanti, con Kris Harrison).

Ho ancora bisogno di aiuto. Cosa posso fare adesso?

• Accedere alle risorse indicate sopra.

• Pubblicare un post nella Trailblazer Community.

• Creare un caso con l'Assistenza Salesforce tramite la Guida di Salesforce. Per ottimizzare l'efficacia del supporto fornito dall'Assistenza, è utile ricordare le operazioni già effettuate e il momento in cui non è più stato possibile proseguire. **Nota: l'Assistenza non può aggiornare le API legacy in uso nelle singole organizzazioni.

Per visualizzare tutti i ritiri attuali e precedenti, vedere Ritiri delle funzioni e dei prodotti Salesforce. Per ulteriori informazioni sull'approccio di Salesforce al ritiro di prodotti e funzionalità, consultare la Filosofia di ritiro delle funzionalità e dei prodotti.