Obter previsões com solicitações REST

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:

Descrever o que é necessário para acessar o Serviço de previsões do Einstein em um cliente REST.
Criar um aplicativo conectado para gerenciar a autenticação das solicitações da API REST.
Usar seu cliente REST para interagir com o Serviço de previsões do Einstein.

Introdução

Agora que seu modelo está implantado no Salesforce, você pode usar o Serviço de previsões do Einstein para obter previsões usando seu cliente REST favorito.

Antes de começar

A organização Developer Edition habilitada para CRM Analytics na qual você se inscreveu na unidade anterior fornece tudo que é necessário para concluir as etapas da unidade.

No entanto, depois de concluir este módulo, os seguintes pré-requisitos serão exigidos para interagir com o Serviço de previsões do Einstein usando um cliente REST.

Licença do CRM Analytics Plus ou licença do Previsões do Einstein, ambas disponíveis mediante um custo adicional.
Uma conta de usuário com a permissão do sistema View Einstein Discovery Recommendations (Exibir recomendações do Einstein Discovery)
Seu cliente REST favorito para enviar solicitações e processar resultados. Nesta unidade, usamos instruções e exemplos de capturas de tela para o aplicativo Postman (versão para computador). No entanto, as tarefas para interagir com os recursos do Serviço de previsões do Einstein são semelhantes na maioria dos clientes REST, portanto, você pode usar uma ferramenta diferente e acompanhar usando etapas semelhantes. Para obter o aplicativo Postman, versão para computador, acesse www.postman.com e vá até a página de download do aplicativo Postman.
Nota: As instruções nesta unidade foram testadas com a versão para computador do Postman. O Postman Web, que requer instruções especiais de configuração para o Salesforce, não foi aprovado para ser usado com este módulo do Trailhead.
O acesso a um aplicativo gerenciado no Salesforce que autoriza solicitações da API REST do seu cliente REST. Para criar um aplicativo conectado no Salesforce, sua conta de usuário deve ter a permissão Manage Connected App (Gerenciar aplicativo conectado).

Nota: O administrador do Salesforce da sua organização pode criar o aplicativo gerenciado para você.

Etapa 1: Criar um aplicativo conectado no Salesforce

Comece criando um aplicativo conectado para que seu cliente REST possa se conectar com segurança à sua organização do Salesforce. Para saber mais, consulte o módulo do Trailhead Noções básicas sobre aplicativos conectados.

Em Setup (Configuração), na caixa Quick Find (Busca rápida), insira apps (aplicativos) e clique em App Manager (Gerenciador de aplicativos).

No Gerenciador de aplicativos do Lightning Experience, clique em New Connected App (Novo aplicativo conectado). Em seguida, na página New Connected App (Novo aplicativo conectado), especifique as seguintes informações básicas.
Tela do Gerenciador de aplicativos do Lightning Experience mostrando o prompt do novo aplicativo conectado para o nome do aplicativo, o nome da API e o email de contato

Tela do Gerenciador de aplicativos do Lightning Experience mostrando o prompt do novo aplicativo conectado para o nome do aplicativo, o nome da API e o email de contato

Configuração	Descrição
Nome do aplicativo conectado	Especifique um nome que seja descritivo e que possa ser facilmente distinguido.
Nome da API	Use a estrutura do Nome da API do Salesforce.
Email do contato	Especifique o endereço de email associado às suas credenciais de usuário.

Em seguida, marque a caixa de seleção Enable OAuth Settings (Habilitar configurações do OAuth) e especifique as seguintes configurações.

Configuração

Descrição

URL de retorno de chamada

Este exemplo usa https://login.salesforce.com/services/oauth2/callback. Você pode usar a URL associada com sua organização Salesforce (por exemplo, https://test.salesforce.com/services/oauth2/callback).

Escopos OAuth selecionados

Adicione os seguintes escopos OAuth selecionados:

Acessar recursos da API REST do Analytics (wave_api)
Gerenciar dados de usuários por meio de APIs (api)

Salve suas configurações e clique em Continue (Continuar) para criar o Aplicativo conectado.
Clique em Manage Consumer Details (Gerenciar detalhes do consumidor).
Se solicitado, forneça a verificação que foi enviada por email para você e clique em Verify (Verificar).

Ao criar o aplicativo conectado, o Salesforce gera duas credenciais: uma Consumer Key (Chave de cliente) e um Consumer Secret (Segredo de cliente).

Tela do Gerenciador de aplicativos do Lightning Experience mostrando a Consumer Key (Chave de cliente) e o Consumer Secret (Segredo de cliente)

Essas são as credenciais que você vai precisar posteriormente quando se conectar do seu cliente REST ao Salesforce por meio do aplicativo conectado.

Sua Consumer Key (Chave de cliente) servirá como sua ID de cliente.
Seu Consumer Secret (Segredo de cliente) servirá como seu segredo de cliente.

Mantenha esta janela aberta para poder copiar a Consumer Key (Chave de cliente) e o Consumer Secret (Segredo de cliente) posteriormente nesta unidade.

Etapa 2: Permitir fluxo entre nome de usuário e senha para OAuth 2.0

Neste módulo, você usará um fluxo entre nome de usuário e senha para autenticação.

Em Setup (Configuração), na caixa Quick Find (Busca rápida), insira oauth e clique em Oauth and Open ID Connect Settings (Configurações de Oauth e OpenID Connect).
Certifique-se de que Allow Oauth Username-Password Flows (Permitir fluxos entre nome de usuário e senha) esteja ativado.

Etapa 3: Configurar a autenticação no cliente REST

Em seguida, vamos configurar a autenticação no seu cliente REST usando as credenciais do Aplicativo conectado que você acabou de criar. O acesso ao Serviço de previsões do Einstein requer autenticação.

Nota: As instruções a seguir usam o cliente Postman (aplicativo para computador) como exemplo, mas você pode usar qualquer cliente da API REST com funcionalidade semelhante.

No Postman, crie um novo espaço de trabalho, se necessário. Em seguida, crie uma nova coleção (opcional, mas recomendado) usando um nome descritivo. Uma coleção armazena todas as solicitações do Serviço de previsões do Einstein em um único local.

Tela do Postman para computador - Nova coleção chamada myEinsteinPredictionServiceRequests

Selecione a coleção na lista, clique em Add request (Adicionar solicitação) e renomeie essa solicitação como Authenticate (Autenticar).
Em seguida, configure os seguintes parâmetros para a solicitação Authenticate (Autenticar).

Configuração

Descrição

Tipo de solicitação

Mudar para POST

URL da solicitação

Especifique https://login.salesforce.com/services/oauth2/token

Clique na guia Body (Corpo), altere o Body Type (Tipo de corpo) para x-www-form-urlencoded e adicione as chaves e valores a seguir.
Tela do Postman para computador - Configurações concluídas do corpo da solicitação

Tela do Postman para computador - Configurações concluídas do corpo da solicitação

Chave	Valor
`grant_type`	Especifique `password` (senha).
`client_id`	Copie e cole a Consumer Key (Chave de cliente) do Aplicativo conectado criado anteriormente.
`client_secret`	Copie e cole o Consumer Secret (Segredo de cliente) do Aplicativo conectado criado anteriormente.
`username` (nome do usuário)	Especifique o nome de usuário da conta associada à sua organização Developer Edition do Trailhead.
`password` (senha)	Especifique a senha da conta associada à sua organização Developer Edition do Trailhead.

Salve a solicitação e clique em Send (Enviar). Se você tiver definido suas configurações corretamente, deverá ver uma resposta semelhante ao exemplo a seguir (observe que as informações de segurança foram intencionalmente ocultadas).
Por fim, conclua as etapas a seguir:

Copie a sequência de caracteres access_token e cole-a em um local para usar posteriormente. Você precisará dela para executar solicitações da API para o Serviço de previsões do Einstein.
Copie a sequência de caracteres instance_URL e cole-a em um local para usar posteriormente. Você precisará dela para solicitações subsequentes.

Agora você pode criar e enviar suas solicitações da API REST para o Serviço de previsões do Einstein!

Etapa 4: Obter definições de previsão disponíveis

Vamos começar recuperando a lista de todas as definições de previsão disponíveis em nossa organização.

Crie uma nova solicitação GET e dê a ela o nome de Get Prediction Definitions (Obter definições de previsão). Configure a solicitação usando as seguintes definições.
Tela do Postman para computador - Começar a configurar a solicitação

Tela do Postman para computador - Começar a configurar a solicitação

Configuração	Descrição
Tipo de solicitação	GET
URL da solicitação	Especifique `instance_URL/services/data/v55.0/smartdatadiscovery/predictionDefinitions`, em que `instance_URL` foi retornada da solicitação de autenticação.

Clique na guia Authorization (Autorização) e defina as seguintes configurações.

Configuração

Descrição

Tipo de autorização

Selecione OAuth2.0.

Configurar token de acesso

Cole o token de acesso salvo na etapa anterior.
Salve a solicitação e clique em Send (Enviar). Se você tiver definido suas configurações de solicitação corretamente, deverá ver uma resposta semelhante ao exemplo a seguir.

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

Etapa 5: Obter metadados das definições de previsão

A resposta da Etapa 3 inclui a URL para recuperar os metadados das definições de previsão criada na unidade anterior. Deve ser parecida com o seguinte exemplo.

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

A ID da previsão corresponde àquela que você viu anteriormente no Gerenciador de modelos.

Adicione uma nova solicitação GET, dê a ela o nome de Get Prediction Definition (Obter definição de previsão) e substitua essa sequência de caracteres de solicitação na URL. Não se esqueça de incluir a instance_Url.
```
instance_Url
/services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2
```

Além disso, defina as configurações da Authorization (Autorização) (Authorization Type [Tipo de autorização] e Access Token [Token de acesso]) como antes. Clique em Send (Enviar) e verifique a resposta. Deve ser parecida com o seguinte exemplo.

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

Etapa 6: Obter modelos associados a uma previsão

A resposta da Etapa 4 inclui a URL para recuperar os metadados do modelo implantado na unidade anterior. Deve ser parecida com o seguinte exemplo.

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

Adicione uma nova solicitação GET, dê a ela o nome de Get Models (Obter modelos) e substitua essa sequência de caracteres de solicitação na URL. Não se esqueça de incluir a instance_Url.
```
instance_Url
/services/data/v55.0/smartdatadiscovery/predictiondefinitions/1ORB00000008RSROA2/models
```

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

Observe fieldMappingList, que fornece a lista de campos no modelo. Vamos usá-los na próxima etapa.

Etapa 7: Obter previsões

Agora que você treinou a interação com o Serviço de previsões do Einstein, vamos obter algumas previsões!

Adicione uma nova solicitação, dê a ela o nome de Get Predictions (Obter previsões) e configure os seguintes parâmetros.
Tela do Postman para computador - Definir as configurações da solicitação para previsões

Tela do Postman para computador - Definir as configurações da solicitação para previsões

Configuração	Descrição
Tipo de solicitação	Mudar para POST
URL da solicitação	Especifique `instance_URL/services/data/v55.0/smartdatadiscovery/predict`, em que `instance_URL` foi retornada da solicitação de autenticação.

Defina as configurações da Authorization (Autorização) (Authorization Type [Tipo de autorização] e Access Token [Token de acesso]) como antes. Em Add Authorization Request To (Adicionar solicitação de autorização para), não se esqueça de selecionar Request Headers (Cabeçalhos de solicitação).
Como se trata de uma chamada POST, precisamos especificar o corpo da solicitação. Clique na guia Body (Corpo) e selecione as seguintes opções.

Configuração

Descrição

Tipo de corpo

Selecione RAW

Solicitação de tipo de corpo

Selecione JSON
Adicione o corpo da solicitação em formato JSON.

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

Substitua yourPredictionDefinitionId pela ID da previsão anteriormente recuperada. Algumas observações sobre o corpo da solicitação.

Elemento	Notas
`"type":"RawData"`	O uso do tipo `RawData` permite especificar valores de entrada brutos diretamente na solicitação de previsão. Existem dois outros tipos, `Records` e `RecordOverrides`, que podem ser usados quando a previsão está associada a um objeto do Salesforce. No entanto, nossa previsão não está associada a um objeto do Salesforce.
`"columnNames"`	Lista separada por vírgulas de nomes que o modelo espera como variáveis de entrada. Eles correspondem ao elemento `"modelField":"Name"` na `fieldMappingList` retornada na resposta da Etapa 5.
`"rows"`	Lista separada por vírgulas de valores de texto que devem ser enviados para o modelo. Essas são as variáveis de entrada que o modelo usa para derivar uma previsão.

Salve sua solicitação, clique em Send (Enviar) e analise a resposta. Deve ser parecida com o seguinte exemplo.

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

O valor "prediction":"total" é a previsão de vendas por cliente que o modelo calculou com base nos seus valores de entrada.

Em seguida, copie e cole o código a seguir no corpo da solicitação (substituindo o que está lá atualmente). Adicione a ID da previsão e clique em Send (Enviar).

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

A resposta deve ser semelhante ao exemplo a seguir (os valores das previsões podem ser diferentes).

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

A ordem das previsões na resposta corresponde à ordem dos valores de entrada no corpo da solicitação.

Por fim, também vamos recuperar os principais fatores e aprimoramentos na resposta. Remova a segunda linha de dados, adicione as seguintes linhas à solicitação e clique em Send (Enviar).

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

Na solicitação:

maxMiddleValues permite o retorno dos principais fatores (até 2, neste exemplo).
maxPrescriptions permite o retorno dos aprimoramentos (até 2, neste exemplo).

A resposta deve ser semelhante ao exemplo a seguir.

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

Na resposta:

O total representa o valor da previsão.
A seção middlevalues descreve os dois principais fatores retornados para esta previsão. Neste exemplo:

Quando Subcategoria = cadeiras e Vendas é 262, o efeito é uma redução na previsão de quase 731 (-730,8852).
Quando Vendas é 262, o efeito é um aumento na previsão em cerca de 245 (244,8200).

Para obter mais informações sobre outros elementos na resposta, consulte Obter previsões na ajuda do Salesforce.

Analisar o monitoramento do uso

O Einstein Discovery monitora as estatísticas de uso em tempo real. Para exibir as estatísticas de uso do na sua organização, em Setup (Configuração), na caixa Quick Find (Busca rápida), insira discovery e selecione Usage (Uso).

Tela do Monitoramento de uso do Einstein Discovery mostrando o número de chamadas à API de previsão executadas hoje

O Einstein rastreia solicitações da API REST, juntamente com outras solicitações de previsão programática, em Number of prediction API calls run today (Número de chamadas à API de previsão executadas hoje).

Tempo estimado

Tópicos

Procurando ajuda?

CRM Analytics Recursos

Einstein Recursos