Ottenere previsioni con le richieste REST

Obiettivi di apprendimento

Al completamento di questa unità, sarai in grado di:

• Descrivere i requisiti necessari per accedere al servizio Previsioni Einstein da un client REST.
  
• Creare un'applicazione connessa per gestire l'autenticazione per le richieste API REST.
  
• Utilizzare il client REST per interagire con il servizio Previsioni Einstein.
  

Introduzione

Ora che hai distribuito il modello in Salesforce, puoi utilizzare il servizio Previsioni Einstein per ottenere previsioni usando il tuo client REST preferito.

Prima di iniziare

L'organizzazione DE in cui è abilitato CRM Analytics e a cui hai eseguito la registrazione nell'unità precedente ti offre tutto ciò che serve per completare i passaggi di questa unità. 

Tuttavia, dopo che avrai completato questo modulo, sarà necessario soddisfare i seguenti prerequisiti per interagire con il servizio Previsioni Einstein utilizzando un client REST.

• Una licenza CRM Analytics Plus o Einstein Predictions, entrambe disponibili con un supplemento di prezzo.
  
• Un account utente con l'autorizzazione di sistema View Einstein Discovery Recommendations (Visualizza i consigli di Einstein Discovery).
  
• Il tuo client REST preferito per inviare le richieste e gestire i risultati. Le istruzioni e le schermate di esempio usate in questa unità si riferiscono all'app Postman (versione desktop). Tuttavia, dato che le operazioni necessarie per interagire con le risorse del servizio Previsioni Einstein sono simili nella maggior parte dei client REST, puoi usare uno strumento diverso e seguire passaggi analoghi. Per scaricare l'app Postman per desktop, vai all'indirizzo www.postman.com e passa alla pagina di download dell'app Postman.
  Nota: le istruzioni fornite in questa unità sono state testate con la versione desktop di Postman. Per questo modulo Trailhead non è stato approvato l'uso di Postman Web, che richiede istruzioni di installazione specifiche per Salesforce.
  
• Accesso a un'app gestita in Salesforce che autorizzi le richieste API REST provenienti dal tuo client REST. Per creare un'applicazione connessa in Salesforce, il tuo account utente deve avere l'autorizzazione Manage Connected App (Gestisci applicazioni connesse).
  

Nota: nella tua organizzazione, l'amministratore Salesforce può creare l'applicazione gestita per te.

Passaggio 1: Creare un'applicazione connessa in Salesforce

Per iniziare, crea un'applicazione connessa per far sì che il client REST possa connettersi in modo sicuro alla tua organizzazione Salesforce. Per saperne di più, vedi il modulo Trailhead Nozioni di base sulle applicazioni connesse.  

1. In Setup (Imposta), nella casella Quick Find (Ricerca veloce), inserisci apps, quindi fai clic su App Manager (Gestore app).
   
   
2. In Lightning Experience App Manager (Gestore app di Lightning Experience), fai clic su New Connected App (Nuova applicazione connessa). Quindi, nella pagina New Connected App (Nuova applicazione connessa), specifica le seguenti informazioni di base.
   
   

   Impostazione	Descrizione
   Connected App Name (Nome applicazione connessa)	Specifica un nome descrittivo e facilmente distinguibile.
   API name (Nome API)	Usa la struttura Salesforce API Name (Nome API Salesforce).
   Contact email (Email referente)	Specifica l'indirizzo email associato alle tue credenziali utente.

3. Successivamente, seleziona la casella di spunta in corrispondenza di Enable OAuth Settings (Abilita impostazioni OAuth) e specifica le impostazioni seguenti.
   
   

4. Salva le impostazioni e fai clic su Continue (Continua) per creare l'applicazione connessa.
   
5. Fai clic su Manage Consumer Details (Gestisci dettagli consumatore).
   
   
6. Se richiesto, fornisci la verifica che ti è stata inviata via email e fai clic su Verify (Verifica).
   
   

Quando crea un'applicazione connessa, Salesforce genera due credenziali: una Consumer Key (Chiave consumatore) e un Consumer Secret (Segreto consumatore).

Queste credenziali ti serviranno più tardi per stabilire la connessione dal client REST a Salesforce attraverso l'applicazione connessa.

• La chiave consumatore sarà il tuo ID client (id_client).
  
• Il segreto consumatore sarà il tuo segreto client (client_secret).
  

Tieni aperta questa finestra per poter copiare la chiave e il segreto consumatore più avanti in questa unità.

Passaggio 2: Consentire il flusso nome utente-password per OAuth 2.0

In questo modulo utilizzerai un flusso nome utente-password per l'autenticazione.

1. In Setup (Imposta), nella casella Quick Find (Ricerca veloce), inserisci oauth e poi fai clic su Oauth and Open ID Connect Settings (Impostazioni OAuth e OpenID Connect).
   
2. Accertati che l'opzione Allow Oauth Username-Password Flows (Consenti flussi nome utente-password OAuth) sia attiva.
   

Passaggio 3: Configurare l'autenticazione nel client REST

Ora passiamo alla configurazione dell'autenticazione nel tuo client REST utilizzando le credenziali dell'applicazione connessa che hai appena creato. L'autenticazione è obbligatoria per accedere al servizio Previsioni Einstein.

Nota: nelle istruzioni seguenti viene usato come esempio il client Postman (app per desktop), ma tu puoi utilizzare qualsiasi client API REST con funzionalità analoghe.

In Postman, crea una nuova area di lavoro (Workspace), se necessario. Quindi, crea una nuova raccolta (New Collection) (facoltativo ma consigliato) usando un nome descrittivo. Una raccolta consente di memorizzare tutte le richieste inviate al servizio Previsioni Einstein in un unico posto.

1. Seleziona la raccolta nell'elenco e fai clic su Add request (Aggiungi richiesta), quindi rinomina la richiesta Authenticate (Autenticazione).
   
   
2. Successivamente, configura i seguenti parametri per la richiesta Authenticate (Autenticazione).
   
   

   Impostazione	Descrizione
   Request Type (Tipo richiesta)	Cambia in POST
   Request URL (URL richiesta)	Inserisci https://login.salesforce.com/services/oauth2/token

3. Fai clic sulla scheda Body (Corpo), cambia Body Type (Tipo di corpo) in x-www-form-urlencoded e aggiungi le chiavi e i valori seguenti.
   
   

   Key (Chiave)	Value (Valore)
   grant_type	Inserisci password.
   client_id	Copia e incolla il contenuto del campo Consumer Key (Chiave consumatore) dell'applicazione connessa che hai creato in precedenza.
   client_secret	Copia e incolla il contenuto del campo Consumer Secret (Segreto consumatore) dell'applicazione connessa che hai creato in precedenza.
   username	Inserisci il nome utente dell'account associato all'organizzazione Trailhead DE.
   password	Inserisci la password dell'account associato all'organizzazione Trailhead DE.

4. Salva la richiesta e fai clic su Send (Invia). Se hai configurato correttamente le impostazioni, dovresti visualizzare una risposta simile alla seguente (nota che le informazioni sulla sicurezza sono state nascoste intenzionalmente).
   
   
5. Infine, completa i passaggi seguenti:
   

• Copia la stringa access_token e incollala da qualche parte per recuperarla in seguito. Ti servirà per eseguire le richieste API per il servizio Previsioni Einstein.
  
• Copia la stringa instance_URL e incollala da qualche parte per recuperarla in seguito. Ti servirà per le richieste successive.
  

Ora puoi iniziare a creare richieste API REST e inviarle al servizio Previsioni Einstein.

Passaggio 4: Recuperare le definizioni delle previsioni disponibili

Per iniziare, recuperiamo l'elenco di tutte le definizioni delle previsioni disponibili nell'organizzazione.

1. Crea una nuova richiesta GET e assegnale il nome Get Prediction Definitions (Recupero definizioni di previsione). Configura la richiesta applicando le seguenti impostazioni.
   
   

   Impostazione	Descrizione
   Request Type (Tipo richiesta)	GET
   Request URL (URL richiesta)	Inserisci instance_URL/services/data/v55.0/smartdatadiscovery/predictionDefinitions, dove instance_URL è il valore restituito dalla richiesta di autenticazione.

2. Fai clic sulla scheda Authorization (Autorizzazione) e configura le seguenti impostazioni.
   
   

   Impostazione	Descrizione
   Authorization Type (Tipo di autorizzazione)	Seleziona OAuth2.0.
   Set Access Token (Imposta token di accesso)	Incolla il token di accesso che hai salvato nel passaggio precedente.

3. Salva la richiesta e fai clic su Send (Invia). Se hai configurato correttamente le impostazioni, dovresti visualizzare una risposta simile all'esempio seguente.
   

{
  "nextPageUrl": null,
  "predictionDefinitions": [
    {
      "countOfActiveModels": 1,
      "countOfModels": 1,
      "createdBy": {
        "id": "your-account-id",
        "name": "your-name",
        "profilePhotoUrl": "https://xxx-instance-url-xxx/profilephoto/005/T"
      },
      "createdDate": "2022-06-09T21:23:54.000Z",
      "id": "1ORB00000008RSROA2",
      "label": "Sales_per_Customer",
      "lastModifiedBy": {
        "id": "your-account-id",
        "name": "your-name",
        "profilePhotoUrl": "https://xxx-instance-url-xxx/profilephoto/005/T"
      },
      "lastModifiedDate": "2022-06-09T21:23:54.000Z",
      "modelsUrl": "/services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2/models",
      "name": "Sales_per_Customer",
      "outcome": {
        "goal": "Maximize",
        "label": "Sales per Customer",
        "name": "Sales_per_Customer"
      },
      "predictionType": "Regression",
      "status": "Enabled",
      "url": "/services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2"
     }
  ],
  "totalSize": 1,
  "url": "/services/data/v55.0/smartdatadiscovery/predictiondefinitions?pageSize=25"
}

Passaggio 5: Recuperare i metadati della definizione della previsione

La risposta nel passaggio 3 include l'URL per recuperare i metadati della definizione della previsione che hai creato nell'unità precedente e dovrebbe essere simile all'esempio seguente.

/services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2

L'ID della previsione corrisponde a quello che hai visto prima nel Gestore modelli. 

1. Aggiungi una nuova richiesta GET, assegnale il nome Get Prediction Definition (Recupera definizione di previsione) e inserisci la stringa di questa richiesta nel campo riservato all'URL. Ricorda di includere il valore instance_Url.
   

   instance_Url
   /services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2

2. Inoltre configura le impostazioni di Authorization (Autorizzazione): Authorization Type (Tipo di autorizzazione) e Access Token (Token di accesso)come hai fatto in precedenza. Fai clic su Send (Invia) ed esamina la risposta, che dovrebbe essere simile all'esempio seguente.
   

   {
     "countOfActiveModels": 1,
     "countOfModels": 1,
     "createdBy": {
       "id": "your-account-id",
       "name": "your-name",
       "profilePhotoUrl": "https://xxx-instance-url-xxx/profilephoto/005/T"
     },
     "createdDate": "2022-06-09T21:23:54.000Z",
     "id": "1ORB00000008RSROA2",
     "label": "Sales_per_Customer",
     "lastModifiedBy": {
       "id": "your-account-id",
       "name": "your-name",
       "profilePhotoUrl": "https://xxx-instance-url-xxx/profilephoto/005/T"
     },
     "lastModifiedDate": "2022-06-09T21:23:54.000Z",
     "modelsUrl": "/services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2/models",
     "name": "Sales_per_Customer",
     "outcome": {
       "goal": "Maximize",
       "label": "Sales per Customer",
       "name": "Sales_per_Customer"
     },
     "predictionType": "Regression",
     "status": "Enabled",
     "url": "/services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2"
   }

Passaggio 6: Recuperare i modelli associati a una previsione

La risposta nel passaggio 4 include l'URL per recuperare i metadati del modello che hai distribuito nell'unità precedente e dovrebbe essere simile all'esempio seguente.

/services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2/models

1. Aggiungi una nuova richiesta GET, assegnale il nome Get Model (Recupera modello) e inserisci la stringa di questa richiesta nel campo riservato all'URL. Ricorda di includere il valore instance_Url.
   

   instance_Url
   /services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2/models

2. Inoltre configura le impostazioni di Authorization (Autorizzazione): Authorization Type (Tipo di autorizzazione) e Access Token (Token di accesso)come hai fatto in precedenza. Fai clic su Send (Invia) ed esamina la risposta, che dovrebbe essere simile all'esempio seguente.
   

   {
     "models": [
       {
         "createdBy": {
           "id": "your-account-id",
           "name": "your-name",
           "profilePhotoUrl": "https://xxx-instance-url-xxx/profilephoto/005/T"
         },
         "createdDate": "2022-06-09T21:23:55.000Z",
         "fieldMappingList": [
           {
             "modelField": {
               "label": "Quantity",
               "name": "Quantity",
               "type": "Number"
             }
           },
           {
             "modelField": {
               "label": "Sub-Category",
               "name": "Sub_Category",
               "type": "Text"
             }
           },
         {
           "modelField": {
             "label": "Category",
             "name": "Category",
             "type": "Text"
           }
         },
         {
           "modelField": {
             "label": "Sales",
             "name": "Sales",
             "type": "Number"
           }
         },
         {
           "modelField": {
             "label": "Profit per Order",
             "name": "Profit_per_Order",
             "type": "Number"
             }
           }
         ],
         "filters": [],
         "historyUrl": "/services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2/models/1ORB00000008RSROA2/histories",
         "id": "1Ot4W000000XezqSAC",
         "isRefreshEnabled": false,
         "label": "Sales_per_Customer",
         "lastModifiedBy": {
           "id": "your-account-id",
           "name": "your-name",
           "profilePhotoUrl": "https://xxx-instance-url-xxx/profilephoto/005/T"
         },
         "lastModifiedDate": "2020-08-31T21:23:55.000Z",
         "model": {
            "id": "1OT4W000000LejUWAS"
         },
         "modelType": "Regression",
         "name": "Sales_per_Customer",
         "predictionDefinitionUrl": "/services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2",
         "prescribableFields": [
           {
             "customDefinitions": [],
             "field": {
               "label": "Quantity",
               "name": "Quantity",
               "type": "Number"
             }
           }
         ],
         "sortOrder": 0,
         "status": "Enabled",
         "url": "/services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2/models/1Ot4W000000XezqSAC"
       }
     ],
     "totalSize": 1,
     "url": "/services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2/models"
   }

Nota il valore fieldMappingList, che fornisce l'elenco dei campi presenti nel modello. Li useremo nel passaggio successivo.

Passaggio 7: Ricevere le previsioni

Ora che hai fatto pratica con le interazioni con il servizio Previsioni Einstein, procuriamoci qualche previsione!

1. Aggiungi una nuova richiesta, assegnale il nome Get Predictions (Ricevi previsioni) e configura i parametri seguenti.
   
   

   Impostazione	Descrizione
   Request Type (Tipo richiesta)	Cambia in POST
   Request URL (URL richiesta)	Inserisci instance_URL/services/data/v55.0/smartdatadiscovery/predict, dove instance_URL è il valore restituito dalla richiesta di autenticazione.

2. Configura le impostazioni di Authorization (Autorizzazione): Authorization Type (Tipo di autorizzazione) e Access Token (Token di accesso) come hai fatto in precedenza. In Add Authorization Data To (Aggiungi dati di autorizzazione a), assicurati di selezionare Request Headers (Intestazioni richiesta).
   
3. Dato che si tratta di una chiamata POST, dobbiamo specificare il corpo della richiesta. Fai clic sulla scheda Body (Corpo) e seleziona le opzioni seguenti.
   

   Impostazione	Descrizione
   Body Type (Tipo di corpo)	Seleziona RAW
   Body Type Request (Richiesta tipo di corpo)	Seleziona JSON

4. Aggiungi il corpo della richiesta nel formato JSON.
   

{  "predictionDefinition": "
yourPredictionDefinitionId
",
   "type": "RawData",
   "columnNames": ["Quantity","Category","Sub_Category","Sales","Profit_per_Order"],
   "rows": [
      ["2","Furniture","Chairs","300","10"]
   ]
}

5. Sostituisci yourPredictionDefinitionId con l' ID previsione che hai recuperato in precedenza. Qualche nota sul corpo della richiesta:
   

   Elemento	Note
   "type":"RawData"	L'uso del tipo RawData ti consente di specificare valori di input non elaborati direttamente nella richiesta di previsione. Esistono altri due tipi, Records e RecordOverrides, che puoi utilizzare quando la previsione è associata a un oggetto Salesforce e quindi non in questo caso.
   "columnNames"	Si tratta dell'elenco di nomi separati da virgole che il modello si aspetta come variabili di input, corrispondenti all'elemento "modelField":"Name" dell'elemento fieldMappingList restituito nella risposta di cui al passaggio 5.
   "rows"	Elenco separato da virgole di valori di testo da inviare al modello. Si tratta delle variabili di input che il modello utilizza per formulare la propria previsione.

6. Salva la richiesta e fai clic su Send (Invia), quindi esamina la risposta, che dovrebbe essere simile all'esempio seguente.
   

{
  "predictionDefinition": "1ORB00000008RSR",
  "predictions": [
      {
        "model": {
          "id": "1OtB00000008S34KAE"
         },
      "prediction": {
        "middleValues": [],
        "total": 88.68177540182317
      },
      "prescriptions": [],
      "status": "Success"
    }
  ],
  "settings": {
    "maxMiddleValues": 0,
    "maxPrescriptions": 0,
    "prescriptionImpactPercentage": 0
  }
}

Il valore "prediction":"total" corrisponde alle vendite per cliente previste che il modello ha calcolato in base ai valori di input.

7. Successivamente, copia e incolla il seguente codice nel corpo della richiesta (sostituendo il codice presente attualmente). Aggiungi l'ID della previsione e fai clic su Send (Invia).
   

{  "predictionDefinition": "yourPredictionDefinitionId",
  "type": "RawData",
  "columnNames": ["Quantity","Category","Sub_Category","Sales","Profit_per_Order"],
  "rows": [
    ["2","Furniture","Chairs","262","42"],
    ["5","Office Supplies","Art","7","25"]   
  ]
}

La risposta dovrebbe essere simile all'esempio seguente (i valori della previsione potrebbero essere diversi).

{
  "predictionDefinition": "1ORB00000008RSR",
  "predictions": [
    {
      "model": {
        "id": "1OtB00000008S34KAE"
      },
      "prediction": {
        "middleValues": [],
        "total": 88.68177540182317
      },
      "prescriptions": [],
      "status": "Success"
    },
    {
      "model": {
        "id": "1OtB00000008S34KAE"
      },
      "prediction": {
        "middleValues": [],
        "total": -155.263449836085
      },
      "prescriptions": [],
      "status": "Success"
    }
  ],
  "settings": {
    "maxMiddleValues": 0,
    "maxPrescriptions": 0,
    "prescriptionImpactPercentage": 0
  }
}

L'ordine delle previsioni nella risposta corrisponde all'ordine dei valori di input nel corpo della richiesta.

8. Infine, recuperiamo anche i fattori principali e i miglioramenti nella risposta. Rimuovi la seconda riga di dati e aggiungi le righe seguenti alla richiesta, quindi fai clic su Send (Invia).
   

{  "predictionDefinition": "yourPredictionDefinitionId",
  "type": "RawData",
  "columnNames": ["Quantity","Category","Sub_Category","Sales","Profit_per_Order"],
  "rows": [
    ["2","Furniture","Chairs","262","42"]
  ],
  "settings": {
    "maxMiddleValues": 2,
    "maxPrescriptions": 2}
}

In questa richiesta:

• maxMiddleValues abilita la restituzione dei fattori principali (fino a 2, in questo esempio).
  
• maxPrescriptions abilita la restituzione dei miglioramenti (fino a 2, in questo esempio).
  

La risposta dovrebbe essere simile all'esempio seguente.

{
  "predictionDefinition": "1ORB00000008RSR",
  "predictions": [
    {
      "model": {
        "id": "1OtB00000008S34KAE"
      },
    "prediction": {
      "baseLine": 438.5059113062626,
      "middleValues": [
        {
        "columns": [
          {
            "columnLabel": "Sub-Category",
            "columnName": "Sub_Category",
            "columnValue": "Chairs"
          },
          {
            "columnLabel": "Sales",
            "columnName": "Sales",
            "columnValue": "262"
          }
        ],
          "value": -730.8852909080902
        },
      {
      "columns": [
        {
          "columnLabel": "Sales",
          "columnName": "Sales",
          "columnValue": "262"
        }
      ],
          "value": 244.82002630727217
          }
        ],
        "other": 136.2411286963786,
        "smallTermCount": 3,
        "total": 88.68177540182317
      },
      "prescriptions": [],
      "status": "Success"
    }
  ],
  "settings": {
    "maxMiddleValues": 2,
    "maxPrescriptions": 2,
    "prescriptionImpactPercentage": 0
  }
}

In questa risposta: 

• total rappresenta il valore della previsione.
  
• La sezione middlevalues descrive i due fattori principali restituiti per questa previsione. In questo esempio:
  

• Quando Sub Category (Sottocategoria) = chairs (sedie) e Sales (Vendite) è 262, l'effetto è una riduzione della previsione di quasi 731 (-730,8852).
  
• Quando Sales (Vendite) è 262, l'effetto è un aumento della previsione di circa 245 (244,8200).
  

Per maggiori informazioni su altri elementi della risposta, leggi gli articoli sulle previsioni nella guida di Salesforce.

Esaminare le informazioni sul monitoraggio dell'utilizzo

Einstein Discovery monitora in tempo reale le statistiche di utilizzo. Per visualizzare le statistiche sull'utilizzo della tua organizzazione, in Setup (Imposta), nella casella Quick Find (Ricerca veloce), inserisci discovery e seleziona Usage (Utilizzo).

Einstein tiene traccia delle richieste API REST, insieme ad altre richieste di previsioni inviate tramite codice, in Number of prediction API calls run today (Numero di chiamate API di previsione eseguite oggi).

Risorse

• Guida di Salesforce: Previsioni e miglioramenti con il servizio Previsioni Einstein
• Guida di Salesforce: Monitoraggio delle statistiche di utilizzo per Einstein Discovery
• Github: Salesforce APIs for Postman (API Salesforce per Postman)