REST 要求を使用して予測を取得する

学習の目的

この単元を完了すると、次のことができるようになります。

• REST クライアントから Einstein 予測サービスにアクセスするために何が必要かを説明する。
• REST API 要求の認証を管理する接続アプリケーションを作成する。
• REST クライアントを使用して Einstein 予測サービスを操作する。

はじめに

ここまでで Salesforce にモデルをリリースしたため、Einstein 予測サービスと任意の REST クライアントを使用して予測を取得できるようになりました。

始める前に

前の単元でサインアップした CRM Analytics が有効な DE 組織には、この単元の手順を完了するのに必要なものがすべて揃っています。 

ただし、このモジュールを完了した後に、REST クライアントを使用して Einstein 予測サービスを操作するには次の前提条件が必要です。

• CRM Analytics Plus ライセンスまたは Einstein Predictions ライセンス。どちらも有料オプションで使用できます。
• 「Einstein Discovery レコメンデーションを表示」システム権限があるユーザーアカウント
• 要求を送信し、結果を処理するための任意の REST クライアント。この単元では、Postman アプリケーション (デスクトップバージョン) の手順と例のスクリーンショットを使用します。ただし Einstein 予測サービスリソースを操作する作業はほとんどの REST クライアントで類似しているため、別のツールを使用して同等の手順を実行してもかまいません。Postman デスクトップアプリケーションを入手するには、www.postman.com にアクセスして Postman アプリケーションのダウンロードページに移動します。
  
  メモ: この単元の手順は Postman デスクトップバージョンでテストされています。Postman Web は、Salesforce で使用するために特別な設定手順が必要であり、この Trailhead モジュールでの使用は認められていません。
• REST クライアントからの REST API 要求を認証する Salesforce 内の管理アプリケーションへのアクセス権。Salesforce で接続アプリケーションを作成するには、ユーザーアカウントに「接続アプリケーションの管理」権限が必要です。

メモ: 組織の Salesforce システム管理者が管理アプリケーションを作成する場合もあります。

ステップ 1: Salesforce で接続アプリケーションを作成する

まず、REST クライアントが安全に Salesforce 組織に接続できるように、接続アプリケーションを作成します。詳細は、「接続アプリケーションの基本」 Trailhead モジュールを参照してください。  

1. [Setup (設定)] の [Quick Find (クイック検索)] ボックスに apps (アプリケーション) と入力し、[App Manager (アプリケーションマネージャー)] をクリックします。
   
   
2. Lightning Experience アプリケーションマネージャーで [New Connected App (新規接続アプリケーション)] をクリックします。次に [新規接続アプリケーション] ページで次の基本情報を指定します。
   
   

   設定	説明
   接続アプリケーション名	わかりやすく、区別しやすい名前を指定します。
   API 参照名	Salesforce API 参照名構造を使用します。
   取引先責任者メールアドレス	自分のユーザーログイン情報に関連付けられたメールアドレスを指定します。

3. 次に [Enable OAuth Settings (OAuth 設定の有効化)] チェックボックスをオンにして、次の設定を指定します。
   
   

   設定	説明
   コールバック URL	この例では https://login.salesforce.com/services/oath2/callback を使用しています。Salesforce 組織に関連付けられている URL (例: https://test.salesforce.com/services/oauth2/callback) を使用できます。
   選択した OAuth 範囲	次の OAuth 範囲を追加します。 Analytics REST API リソースにアクセス (wave_api) API を使用してユーザーデータを管理 (api)

4. 設定を保存し、[Next (次へ)] をクリックして接続アプリケーションを作成します。
5. [Manage Consumer Details (コンシューマーの詳細を管理)] をクリックします。
   
6. メールで受信した確認コードの入力を促されたら、入力して [Verify (検証)] をクリックします。
   

接続アプリケーションを使用すると、コンシューマー鍵とコンシューマーの秘密の 2 つのログイン情報が生成されます。

これは後で接続アプリケーションを使用して REST クライアントから Salesforce に接続するときに必要になるログイン情報です。

• コンシューマー鍵はクライアント ID として機能します。
• コンシューマーの秘密はクライアントの秘密として機能します。

この単元の後の方でコンシューマー鍵とコンシューマーの秘密をコピーできるように、このウィンドウを開いたままにしておきます。

ステップ 2: REST クライアントで認証を設定する

次に、今作成した接続アプリケーションのログイン情報を使用して、REST クライアントで認証を設定しましょう。Einstein 予測サービスにアクセスするには認証が必要です。
メモ: 次の手順では例として Postman クライアント (デスクトップアプリケーション) を使用していますが、同等の機能を持つ任意の REST API クライアントを使用できます。

Postman で、必要に応じて新しいワークスペースを作成します。次に、わかりやすい名前を使用して新しいコレクションを作成します (省略可能ですが推奨します)。コレクションでは、すべての Einstein 予測サービス要求が 1 か所に保存されます。

1. リストからコレクションを選択し、[Add request (要求を追加)] をクリックし、この要求の名前を「Authenticate」 (認証) に変更します。
   
   
2. 次に、Authenticate 要求の次のパラメーターを設定します。
   
   

   設定	説明
   Request Type (要求種別)	[POST] に変更します。
   Request URL (要求 URL)	https://login.salesforce.com/services/oauth2/token と指定します。

3. [Body (ボディ)] タブをクリックし、ボディ種別を [x-www-form-urlencoded] に変更してから、次のキーと値を追加します。
   
   

   Key (キー)	値
   grant_type	password と指定します。
   client_id	先ほど作成した接続アプリケーションからコンシューマー鍵をコピーして貼り付けます。
   client_secret	先ほど作成した接続アプリケーションからコンシューマーの秘密をコピーして貼り付けます。
   username	DE Trailhead 組織に関連付けられているアカウントのユーザー名を指定します。
   password	DE Trailhead 組織に関連付けられているアカウントのパスワードを指定します。

4. 要求を保存し、[Send (送信)] をクリックします。設定が正しい場合は、次の例のような応答が表示されます (セキュリティ情報は意図的に伏せ字にしています)。
   
5. 最後に次の手順を実行します。
   • access_token の文字列をコピーして、後で使用できるようにどこかに貼り付けます。Einstein 予測サービスの API 要求を実行するときにこれが必要になります。
   • instance_URL の文字列をコピーして、後で使用できるようにどこかに貼り付けます。後続の要求でこれが必要になります。

これで REST API 要求を作成して Einstein 予測サービスに送信する準備が整いました。

ステップ 3: 使用可能な予測定義を取得する

まず、組織で使用可能なすべての予測定義のリストを取得しましょう。

1. 新しい GET 要求を作成し、「Get Prediction Definitions」 (予測定義の取得) という名前を付けます。次の設定を使用して要求を設定します。
   
   

   設定	説明
   Request Type (要求種別)	GET
   Request URL (要求 URL)	instance_URL/services/data/v55.0/smartdatadiscovery/predictionDefinitions と指定します。ここで、instance_URL は認証要求から返されたものです。

   
   
2. [Authorization (認証)] タブをクリックし、次の設定を行います。
   
   

   設定	説明
   Authorization Type (認証種別)	[OAuth2.0] を選択します。
   Set Access Token (アクセストークンの設定)	前のステップで保存したアクセストークンを貼り付けます。

   
   
3. 要求を保存し、[Send (送信)] をクリックします。設定が正しい場合は、次の例のような応答が表示されます。

{
  "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"
}

ステップ 4: 予測定義メタデータを取得する

ステップ 3 の応答には、前の単元で作成した予測定義のメタデータを取得するための URL が含まれています。次の例のようになります。

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

予測 ID は先ほどモデルマネージャーに表示されたものと一致します。 

1. 新しい GET 要求を追加し、「Get Prediction Definition」 (予測定義の取得) という名前を付け、URL を次の要求文字列に置き換えます。必ず instance_Url を含めます。
   
   

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

2. また、前と同じように認証設定 (認証種別とアクセストークン) を指定します。[Send (送信)] をクリックし、応答を確認します。次の例のようになります。
   

   {
     "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"
   }

ステップ 5: 予測に関連付けられたモデルを取得する

ステップ 4 の応答には、前の単元でリリースしたモデルのメタデータを取得するための URL が含まれています。次の例のようになります。

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

1. 新しい GET 要求を追加し、「Get Models」 (モデルの取得) という名前を付け、URL を次の要求文字列に置き換えます。必ず instance_Url を含めます。
   
   

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

2. また、前と同じように認証設定 (認証種別とアクセストークン) を指定します。[Send (送信)] をクリックし、応答を確認します。次の例のようになります。
   
   

   {
     "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"
   }

fieldMappingList にはモデル内の項目のリストが含まれます。これは次のステップで使用します。

ステップ 6: 予測を取得する

Einstein 予測サービスの操作を練習できたため、次は予測を取得しましょう。

1. 新しい要求を追加し、「Get Predictions」 (予測の取得) という名前を付け、次のパラメーターを設定します。
   
   

   設定	説明
   Request Type (要求種別)	[POST] に変更します。
   Request URL (要求 URL)	instance_URL/services/data/v55.0/smartdatadiscovery/predict と指定します。ここで、instance_URL は認証要求から返されたものです。

2. 前と同じように認証設定 (認証種別とアクセストークン) を指定します。[Add Authorization Request To (認証要求の追加先)] では、必ず [Request Headers (要求ヘッダー)] を選択してください。
3. これは POST コールなので、リクエストボディを指定する必要があります。[Body (ボディ)] タブをクリックし、次のオプションを選択します。
   
   

   設定	説明
   Body Type (ボディ種別)	[RAW (未加工)] を選択します。
   Body Type Request (ボディ種別要求)	[JSON] を選択します。

4. リクエストボディを JSON 形式で追加します。

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

1. yourPredictionDefinitionId を、先ほど取得した予測 ID に置き換えます。このリクエストボディについて次の点に注意してください。
   
   

   要素	メモ
   "type": "RawData"	RawData 種別を使用すると、予測要求で未加工の入力値を直接指定できます。その他に、予測が Salesforce オブジェクトに関連付けられている場合に使用できる Records と RecordOverrides の 2 つの種別があります。ただし、この例の予測は Salesforce オブジェクトに関係していません。
   "columnNames"	モデルで入力変数として想定される名前のカンマ区切りリスト。これはステップ 5 で返された応答の fieldMappingList の "modelField": "Name" 要素に対応しています。
   "rows"	モデルに送信するテキスト値のカンマ区切りリスト。これはモデルで予測を得るために使用される入力値です。

   
   
2. 要求を保存し、[Send (送信)] をクリックし、応答を確認します。次の例のようになります。

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

"prediction": "total" の値は、入力値に基づいてモデルで計算された顧客あたりの予測売上です。

1. 次のコードをコピーしてリクエストボディに貼り付けます (元の内容を置き換えます)。予測 ID を追加し、[Send (送信)] をクリックします。

{  "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"]    
  ]
}

応答は次の例のようになります (予測値は異なる可能性があります)。

{
  "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
  }
}

応答内の予測の順序はリクエストボディ内の入力値の順序と一致します。

1. 最後に、応答で上位の要素と改善も取得しましょう。データの 2 行目を削除して、次の行を要求に追加し、[Send (送信)] をクリックします。

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

この要求の次の点に注目してください。

• maxMiddleValues によって上位の要素 (この例では最大 2 件) を返せるようになります。
• maxPrescriptions によって改善 (この例では最大 2 件) を返せるようになります。

応答は次の例のようになります。

{
  "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
  }
}

この応答の次の点に注目してください。 

• total は予測値を表します。
• middlevalues セクションはこの予測で返される 2 つの上位の要素についての記述です。この例では次のようになります。
  • サブカテゴリが chairs (椅子) で売上が 262 の場合、その効果によって予測がほぼ 731 (-730.8852) 減少します。
  • 売上が 262 の場合、その効果によって予測が約 245 (244.8200) 増加します。

応答内のその他の要素についての詳細は、Salesforce ヘルプの「予測の取得」を参照してください。

利用状況の監視を確認する

Einstein Discovery はリアルタイムに利用状況統計を監視します。組織の利用状況統計を表示するには、[Setup (設定)] から [Quick Find (クイック検索)] ボックスに discovery と入力し、[Usage (利用状況)] を選択します。

Einstein は REST API 要求とその他のプログラムによる予測要求を [今日実行する予測 API コール数] で監視します。

リソース

• Salesforce ヘルプ: Einstein 予測サービスを使用した予測と改善の取得
• Salesforce ヘルプ: Einstein Discovery の利用状況統計の監視
• Github: Salesforce APIs for Postman (Postman 用の Salesforce API)