通过 REST 请求获取预测
学习目标
完成本单元后，您将能够：
- 描述从 REST 客户端访问 Einstein 预测服务所需的条件。
- 创建连接的应用程序来管理 REST API 请求的身份验证。
- 使用您的 REST 客户端与 Einstein 预测服务交互。
简介
现在您的模型显示在 Salesforce 中，您可以使用 Einstein 预测服务使用您喜欢的 REST 客户端获取预测。
开始之前
您在上一单元中注册的启用 CRM Analytics 的 DE 组织为您提供了完成本单元中步骤所需的一切。
但是，在您完成本模块后，使用 REST 客户端与 Einstein 预测服务交互需要满足以下先决条件。
- CRM Analytics Plus 许可证或 Einstein 预测许可证，两者都需要额外付费。
- 具有查看 Einstein Discovery 推荐系统权限的用户帐户
- 您最喜欢的 REST 客户端，用于提交请求和处理结果。在本单元中，我们使用 Postman 应用程序（桌面版）的说明和示例屏幕截图。但是，在大多数 REST 客户端中，与 Einstein 预测服务资源交互的任务是相似的，因此欢迎您使用不同的工具并使用类似的步骤进行操作。要获取 Postman 桌面应用程序，前往 www.postman.com 并导航到 Postman 应用程序下载页面。
注意：本单元中的说明已使用 Postmand 桌面版进行过测试。Postman Web 需要 Salesforce 特别设置说明，尚未获准与此 Trailhead 模块一起使用。 - 访问 Salesforce 中的托管应用程序，该应用程序授权来自 REST 客户端的 REST API 请求。要在 Salesforce 创建连接的应用程序，您的用户帐户必须具有管理连接的应用程序权限。
注意：在您的组织中，您的 Salesforce 管理员可能为您创建了托管应用程序。
步骤 1：在 Salesforce 中创建连接的应用程序
从创建连接的应用程序开始，这样您的 REST 客户端可以安全地连接到您的 Salesforce 组织。要了解更多，请参阅连接的应用程序概述 Trailhead 模块。
- 在“设置”中的“快速查找”框内输入
apps（应用程序），并单击 App Manager（应用程序管理器）。
- 在 Lightning Experience 应用程序管理器中，单击 New Connected App（新建连接的应用程序）。然后在新建连接的应用程序页面，指定以下基本信息。
设置 描述 连接的应用程序名称 指定描述性且易于分辨的名称。 API 名称 使用 Salesforce API 名称结构。 联系人电子邮件 指定与您的用户凭据关联的电子邮件地址。 - 下一步，勾选 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)
- 保存您的设置，然后单击继续创建连接的应用程序。
- 单击 Manage Consumer Details（管理使用者详细信息）。
- 如果出现提示，请提供通过电子邮件发送给您的验证，然后单击 Verify（验证）。
创建连接的应用程序时，Salesforce 会生成两个凭据：使用者密钥和使用者密码。
这些是稍后通过此连接的应用程序从 REST 客户端连接到 Salesforce 时所需的凭据。
- 您的使用者密钥用作客户端 ID。
- 您的使用者密码用作客户端密码。
将使此窗口保持打开状态，这样您稍后可以在本单元中复制使用者密钥和使用者密码。
步骤 2：在 REST 客户端设置身份验证
下一步，让我们使用您刚刚创建的连接的应用程序凭据在 REST 客户端中设置身份验证。访问 Einstein 预测服务需要身份验证。
注意：以下说明以 Postman 客户端（桌面应用程序）为例，但您可以使用具有类似功能的任何 REST API 客户端。
在 Postman 中，创建新的工作区（如必要）。然后，使用描述性名称创建新合集（可选，但是推荐）。集合将所有 Einstein 预测服务请求存储在一个位置。
- 选择列表中的集合，单击 Add request（添加请求），然后将此请求重命名为 Authenticate（身份验证）。
- 接下来，为身份验证请求配置以下参数。
设置 描述 Request Type（请求类型） 更改为 POST Request URL（请求 URL） 指定为 https://login.salesforce.com/services/oauth2/token
- 单击 Body（正文）选项卡，将正文类型更改为 x-www-form-urlencoded，然后添加以下密钥和值。
密钥 值 grant_type指定 password。client_id从您之前创建的连接的应用程序中复制和粘贴使用者密钥。 client_secret从您之前创建的连接的应用程序中复制和粘贴使用者密码。 username指定与您的 DE Trailhead 组织关联的帐户的用户名。 password指定与您的 DE Trailhead 组织关联的帐户的密码。
- 保存请求，然后单击 Send（发送）。如果您已正确配置设置，您应该会看到类似于以下示例的响应（请注意，安全信息已被故意模糊处理）。
- 最后，完成以下步骤：
- 复制
access_token字符串，然后稍后将其粘贴到某处。您需要此字符串来运行 Einstein 预测服务的 API 请求。 - 复制
instance_URL字符串，然后稍后将其粘贴到某处。您需要此字符串用于随后的请求。
- 复制
现在您已创建并提交您的 REST API 请求至 Einstein 预测服务！
步骤 3：获取可用预测定义
让我们先检索组织中所有可用预测定义的列表。
- 创建一个新的 GET 请求然后将其命名为 Get Prediction Definitions（获取预测定义）。使用以下设置配置请求。
设置 描述 Request Type（请求类型） GET Request URL（请求 URL） 指定 instance_URL/services/data/v55.0/smartdatadiscovery/predictionDefinitions，其中instance_URL从您的身份验证请求返回。
- 单击 Authorization（身份验证）选项卡，然后配置以下设置。
设置 描述 Authorization Type（授权类型） 选择 OAuth2.0。 Set Access Token（设置访问令牌） 粘贴您在上一步中保存的访问令牌。
- 保存请求，然后单击 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 与您之前在模型管理器中看到的预测 ID 匹配。
- 添加新的 GET 请求，将其命名为 Get Prediction Definition（获取预测定义），并在 URL 中替换此请求字符串。记得包括
instance_Url。instance_Url/services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2
- 另外，像以前一样配置身份验证设置（身份验证类型和访问令牌）。单击 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
- 添加新的 GET 请求，将其命名为 Get Models（获取模型），并在 URL 中替换此请求字符串。记得包括
instance_Url。instance_Url/services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2/models
- 另外，像以前一样配置身份验证设置（身份验证类型和访问令牌）。单击 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 预测服务的交互，我们来获取一些预测！
- 添加新请求，将其命名为 Get Predictions（获取预测），然后配置以下参数。
设置 描述 Request Type（请求类型） 更改为 POST Request URL（请求 URL） 指定 instance_URL/services/data/v55.0/smartdatadiscovery/predict，其中instance_URL从您的身份验证请求返回。
- 像以前一样配置授权设置（授权类型和访问令牌）。对于 Add Authorization Request To（添加授权至），确保选择 Request Headers（请求标头）。
- 因为这是一个 POST 调用，我们需要指定请求正文。单击 Body（正文）选项卡，然后选择以下选项。
设置 描述 Body Type（正文类型） 选择 RAW Body Type Request（正文类型请求） 选择 JSON
- 使用 JSON 格式添加请求正文。
{ "predictionDefinition": "yourPredictionDefinitionId",
"type": "RawData",
"columnNames": ["Quantity","Category","Sub_Category","Sales","Profit_per_Order"],
"rows": [
["2","Furniture","Chairs","300","10"]
]
}
- 用您之前检索的预测 ID 替换
yourPredictionDefinitionId。有关此请求正文的一点说明。元素 备注 "type": "RawData"使用 RawData类型允许我们直接在预测请求中指定原输入值。有两种其他类型Records和RecordOverrides，您可以在预测与 Salesforce 对象关联时使用。但是，我们的预测和 Salesforce 对象不相关。"columnNames"模型期望作为输入变量的名称列表，用逗号分隔。对应步骤 5 响应中返回的 fieldMappingList中的"modelField": "Name”元素。"rows”要发送到模型的文本值列表，用逗号分隔。这些是模型用于派生预测的输入变量。
- 保存您的请求，单击 Send（发送），并查看响应。看起来和以下示例类似。
{
"predictionDefinition": "1ORB00000008RSR",
"predictions": [
{
"model": {
"id": "1OtB00000008S34KAE"
},
"prediction": {
"middleValues": [],
"total": 88.68177540182317
},
"prescriptions": [],
"status": "Success"
}
],
"settings": {
"maxMiddleValues": 0,
"maxPrescriptions": 0,
"prescriptionImpactPercentage": 0
}
}
"prediction": "total” 值是模型根据您的输入值计算得出的每位客户的预计销售额。
- 接下来，复制和粘贴以下代码至您的请求正文（替换当前内容）。添加您的预测 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
}
}
响应中预测的顺序与请求正文中输入值的顺序匹配。
- 最后，我们来检索响应中的主要因素和改进。删除数据的第二行，将以下行添加到您的请求，然后单击 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部分描述了为此预测返回的两个主要因素。在本示例中：- 当子类别是 chairs（椅子）且销售额为 262 时，效果是预测减少近 731 (-730.8852)。
- 当销售额是 262 时，效果是预测增加约 245 (244.8200)。
有关响应中其他元素的更多信息，请参阅 Salesforce 帮助中的获取预测。
检查使用情况监控
Einstein Discovery 会实时监控使用情况统计数据。要查看组织的使用情况统计信息，在“设置”中的“快速查找”框内输入 discovery（发现），然后选择 Usage（使用情况）。
Einstein 会跟踪 REST API 请求，以及今天运行的预测 API 调用数量下的其他编程预测请求。