Chamadas externas
As chamadas externas permitem a inclusão de dados de APIs fora do Microsoft Dynamics 365 Fraud Protection e, depois, usam os dados para tomar decisões fundamentadas em tempo real. Por exemplo, serviços de terceiros e de verificação telefônica, ou seus próprios modelos de pontuação personalizados, podem fornecer uma entrada crítica que ajuda a determinar o nível de risco para alguns eventos. Ao usar chamadas externas, você pode se conectar a um ponto de extremidade de API, fazer uma solicitação a esse ponto de extremidade seguindo sua regra, conforme necessário, e usar a resposta desse ponto de extremidade para tomar uma decisão.
Observação
Se esses dados adicionais forem necessários para todos os eventos, você também poderá enviá-los como parte do esquema de avaliação. Para obter mais informações sobre como enviar dados personalizados como parte de uma solicitação de API, consulte Exemplo de dados personalizados.
Tipos de APIs que podem ser usadas em uma chamada externa
Antes de criar uma chamada externa, você deve conhecer as seguintes limitações:
- O Fraud Protection no momento dá suporte apenas aos seguintes métodos de autenticação: Anônimo e AAD.
- O Fraud Protection no momento dá suporte apenas aos seguintes métodos HTTP: GET e POST.
Criar uma chamada externa
No portal do Fraud Protection, na navegação à esquerda, selecione Chamadas Externas e, depois, selecione Nova chamada externa.
Revise e defina os campos a seguir conforme necessário.
Nome – Insira o nome que você usará para fazer referência à chamada externa de suas regras. O nome só pode conter números, letras e sublinhados. Ele não pode começar com um número.
Observação
Não é possível alterar o nome de uma chamada externa após usá-la em uma regra.
Descrição – adicione uma descrição para ajudar a equipe a identificar rapidamente a chamada externa.
Solicitação da Web – Selecione o método HTTP apropriado (GET ou POST) e, depois, insira o ponto de extremidade da API.
Observação
Só há suporte para pontos de extremidade HTTPS.
Habilitar chamadas de aquecimento periódicas – se o tráfego para o ponto de extremidade de chamada externa for muito baixo, a conexão poderá esfriar e aumentar a latência de resposta do serviço externo. Para atenuar esse problema, habilite as chamadas de aquecimento na página Configuração de chamada externa. Use o botão de alternância para ativar as chamadas de aquecimento. Você deve fornecer uma URL de manutenção de atividade GET válida. Assim como acontece com o endpoint primário, o endpoint keep-alive também deve passar pela conexão de teste. Se você configurar sua chamada externa com chamadas de aquecimento habilitadas, quando o volume de tráfego cair muito, o Fraud Protection fará automaticamente chamadas de aquecimento anônimas para o ponto de extremidade keep-alive usando apenas o método GET.
Observação
Nenhum parâmetro, configuração ou cabeçalho configurável pode ser usado em chamadas de aquecimento.
Autenticação – Selecione o método que deve ser usado para autenticar solicitações de entrada.
- Se você selecionar Anônimo, um cabeçalho de autorização não será enviado.
- Se você selecionar AAD, um token do Azure Active Directory (Azure AD) será gerado em seu locatário e o token> de portador <será usado como o cabeçalho de autorização.
Para obter mais informações sobre autenticação, autorização e tokens do Azure AD, consulte a seção Entender autenticação e autorização mais adiante neste artigo.
Audiência – se você selecionar AAD como o método de autenticação, será solicitado que você forneça uma audiência. Você pode usar um aplicativo existente do Azure como público-alvo ou criar um novo por meio da experiência de integração no portal do Fraud Protection. Certifique-se de que o público-alvo tenha permissão para acessar a chamada/serviço externo. Para saber mais sobre como configurar a autenticação do Azure Active Directory (Azure AD), consulte Configurar a autenticação do Azure AD.
ID do aplicativo – você também precisa fornecer a ID do aplicativo de um aplicativo Azure AD novo ou existente em seu locatário de assinatura do Fraud Protection. Gere um certificado no seu Azure Key Vault. O aplicativo Fraud Protection deve ter acesso de leitura nesse Azure Key Vault. Carregue o certificado nesse aplicativo Azure AD. Para obter mais informações sobre como criar e gerenciar aplicativos do Azure AD, consulte Criar aplicativos do Azure Active Directory.
URL do Certificado – forneça a URL do identificador do certificado em seu Azure Key Vault. Este é o mesmo certificado que você carregou no aplicativo Azure AD na etapa anterior. Para obter mais informações sobre como gerar um certificado no Azure Key Vault, consulte Criando e mesclando uma solicitação de assinatura de certificado no Azure Key Vault
Adicionar parâmetro – você pode usar parâmetros para passar dados do Fraud Protection para o ponto de extremidade de API. Dependendo do método HTTP selecionado, esses parâmetros são enviados ao ponto de extremidade na cadeia de caracteres de consulta ou como parte do corpo da solicitação.
Você pode adicionar valores de exemplo para cada parâmetro. O Fraud Protection usa esses valores de parâmetro para fazer uma chamada de amostra para o endpoint, antes da criação ou sempre que você selecionar Testar.
Observação
Todos os valores de parâmetro são interpretados como cadeias de caracteres.
Exemplo de solicitação – forneça um exemplo da solicitação enviada para a chamada externa. A solicitação deve refletir os nomes de parâmetros e os valores especificados por você e não pode ser editada.
Para métodos GET, a URL da solicitação é mostrada. Para métodos POST, o corpo da solicitação é mostrado.
O exemplo de solicitação é usado em um exemplo de chamada para o ponto de extremidade, antes da criação ou sempre que você seleciona Testar.
Exemplo de resposta – forneça um exemplo dos dados que são retornados em uma resposta com êxito do seu ponto de extremidade de API. Esses dados devem estar no formato JSON (JavaScript Object Notation) e podem ser referenciados em suas regras. O exemplo fornecido aqui é mostrado conforme você cria regras.
Selecione Testar para inserir automaticamente uma resposta real da API neste campo.
Tempo limite – especifique o tempo, em milissegundos, que a solicitação deve aguardar até atingir o tempo limite. Você deve especificar um número entre 1 e 1000.
Resposta padrão – especifique a resposta padrão que deverá ser retornada se a solicitação falhar ou exceder o tempo limite especificado. O valor deve ser um objeto JSON ou um elemento JSON válido.
Opcional: para enviar um exemplo de solicitação para o ponto de extremidade de API e exibir a resposta, selecione Testar. Para obter mais informações, consulte a próxima seção, Testar uma chamada externa.
Quando terminar de definir os campos obrigatórios, selecione Criar.
Testar uma chamada externa
Para garantir que Fraud Protection se conecte ao ponto de extremidade, teste a conexão a qualquer momento.
Para testar uma conexão ao criar uma nova chamada externa ou editar uma chamada externa existente, defina todos os campos obrigatórios e, depois, selecione Testar.
O Fraud Protection usa o ponto de extremidade e parâmetros que você forneceu para enviar uma solicitação à chamada externa.
- Se Fraud Protection atingir com êxito o ponto de extremidade de destino, uma barra de mensagens verde aparecerá na parte superior do painel para informá-lo de que a conexão foi bem-sucedida. Para exibir a resposta completa, selecione Consulte detalhes da resposta.
- Se o Fraud Protection não puder atingir o ponto de extremidade de destino ou se não receber uma resposta antes do tempo limite especificado, uma barra de mensagem vermelha aparecerá na parte superior do painel e mostrará o erro encontrado. Para exibir mais informações sobre o erro, selecione Consulte detalhes do erro.
Monitorar chamadas externas
Monitorar chamadas externas no portal do Fraud Protection
O Fraud Protection mostra um bloco que contém três métricas para cada chamada externa que você define:
- Solicitações por segundo – o número total de solicitações dividido pelo número total de minutos no período selecionado.
- Latência média – o número total de solicitações dividido pelo número total de minutos no período selecionado.
- Taxa de sucesso – o número total de solicitações bem-sucedidas dividido pelo número total de solicitações feitas.
Os números e os gráficos mostrados neste bloco incluem somente os dados do período selecionado na lista suspensa no canto superior direito da página.
Observação
As métricas são mostradas somente quando a chamada externa é usada em uma regra ativa.
Para aprofundar-se nos dados sobre a chamada externa, selecione Desempenho no canto direito do bloco.
O Fraud Protection mostra uma nova página com uma visão mais detalhada das métricas.
Para exibir métricas de qualquer período nos últimos três meses, ajuste a configuração de Intervalo de datas na parte superior da página.
Além das três métricas que foram descritas anteriormente, um gráfico de Erro é exibido. Este gráfico mostra o número de erros por tipo de erro e código. Para exibir contagens de erros ao longo do tempo ou para exibir a distribuição de erros, selecione Gráfico de pizza.
Além de erros de cliente HTTP (400, 401 e 403), você poderá ver os seguintes erros:
- ID de aplicativo inválida – a ID do aplicativo fornecida não existe no locatário ou ela não é válida.
- Falha do AAD – não foi possível recuperar o token do Azure AD.
- Definição não encontrada – a chamada externa foi excluída, mas ela ainda é referenciada em uma regra.
- Tempo limite – a solicitação ao destino demorou mais do que o tempo limite especificado.
- Falha de comunicação – não foi possível estabelecer conexão com o destino devido a um problema de rede ou porque o destino não está disponível.
- Disjuntor – Se a chamada externa falhou continuamente e excedeu um determinado limite, todas as chamadas adicionais serão suspensas por um curto intervalo.
- Falha desconhecida – ocorreu uma falha interna do Dynamics 365.
Usar rastreamento de eventos para monitorar chamadas externas
Você pode usar o recurso de rastreamento de eventos do Fraud Protection para encaminhar eventos relativos a chamadas externas para suas próprias instâncias de Hubs de Eventos do Azure ou do Azure Storage Blob. No portal do Fraud Protection, na página Rastreamento de Eventos, você pode inscrever-se nestes dois eventos relacionados a chamadas externas:
- FraudProtection.Monitoring.ExternalCalls
- FraudProtection.Errors.ExternalCalls
Sempre que uma solicitação é feita para uma chamada externa, um evento é enviado ao namespace FraudProtection.Monitoring.ExternalCalls. O payload do evento inclui informações sobre a latência da chamada, o status da solicitação, a regra e a cláusula da qual a solicitação foi disparada.
Quando uma chamada externa falha, um evento é enviado ao namespace FraudProtection.Errors.ExternalCalls. O payload do evento inclui a solicitação de URI e o corpo que foram enviados à chamada externa e a resposta recebida.
Para obter mais informações sobre o rastreamento de eventos, como inscrever-se em eventos e o que é possível fazer com eventos, consulte Rastreamento de eventos.
Para obter informações sobre como integrar esses dados com os fluxos de trabalho de sua própria organização e configurar monitoramento, alerta e relatório personalizados, consulte Extensibilidade via Hubs de Eventos.
Gerenciar chamadas externas
Para editar uma chamada externa existente, selecione Editar no cabeçalho do cartão.
Observação
Não é possível alterar o nome e parâmetros de uma chamada externa após usá-la em uma regra.
Para excluir uma chamada externa existente, selecione as reticências (...) e, depois, selecione Excluir.
Observação
Não é possível excluir uma chamada externa após ela ser referenciada em uma regra.
Para exibir métricas de desempenho detalhadas para uma chamada externa, selecione Desempenho.
Para testar se o Fraud Protection ainda pode se conectar à chamada externa, selecione as reticências (...) e, depois, Testar conexão.
Usar uma chamada externa em regras
Para usar chamadas externas para tomar decisões, referencie-as em suas regras.
Por exemplo, para referenciar uma chamada externa denominada myCall na sua regra, use a seguinte sintaxe:
External.myCall()
Se myCall exigir um parâmetro, como IPAddress, use a seguinte sintaxe:
External.myCall(@"device.ipAddress")
Para obter informações sobre a linguagem de regras e como usar chamadas externas em regras, consulte o Guia de referência de linguagem.
Observação
Se as chamadas externas forem usadas em uma regra, a latência da regra poderá aumentar.
Compreender autenticação e autorização
Para garantir que os dados sejam acessados de forma segura, as APIs costumam autenticar o remetente de uma solicitação para verificar se ele tem permissão para acessar os dados. As chamadas externas no Fraud Protection dão suporte a dois métodos de autenticação: Anônimo e AAD.
Se você selecionar Anônimo, o cabeçalho de autorização na solicitação HTTP para o ponto de extremidade de destino será deixado em branco. Use esta opção quando o ponto de extremidade de destino não exigir um cabeçalho de autorização. Por exemplo, se o ponto de extremidade usar uma chave de API, configure o par chave-valor como parte da URL da solicitação inserida no campo Solicitação da Web. O ponto de extremidade de destino poderá ser validado se a chave de API da URL da solicitação for permitida. Depois, decida se a permissão deve ser concedida.
Se você selecionar AAD, o cabeçalho de autorização na solicitação HTTP para o ponto de extremidade de destino incluirá um token de portador. Um token de portador é um Token Web JSON (JWT) emitido pelo Azure AD. Para obter informações sobre JWTs, consulte tokens de acesso da plataforma de identidade da Microsoft. O Fraud Protection anexa o valor de token ao texto "Portador" no formato exigido no cabeçalho de autorização de solicitação, conforme mostrado aqui:
<Token> do portador
Declarações de token
A tabela a seguir lista as declarações esperadas em tokens de portadores emitidos pelo Fraud Protection.
| Nome | Declaração | Descrição |
|---|---|---|
| ID de locatário | tid | Esta declaração identifica a ID de locatário do Azure da assinatura associada à conta do Fraud Protection. Para obter informações sobre como encontrar sua ID de locatário no portal do Fraud Protection, consulte IDs e informações necessárias. Para obter informações sobre como encontrar sua ID de locatário no portal do Azure, consulte Como encontrar sua ID de locatário do Azure Active Directory. |
| Público-alvo | aud | Essa declaração identifica o destinatário pretendido do token. O valor reflete exatamente a ID do aplicativo que você forneceu ao configurar sua chamada externa no portal do Fraud Protection. |
| ID do aplicativo | appid | Esta reivindicação é o ID do aplicativo do Fraud Protection: * bf04bdab-e06f-44f3-9821-d3af64fc93a9*. Essa ID pertence exclusivamente ao Fraud Protection e somente a Microsoft pode solicitar um token em seu nome. |
Quando a API recebe um token, ela deve abrir o token e validar que cada uma das declarações anteriores corresponda à sua descrição.
Veja um exemplo que mostra como você pode autenticar uma solicitação de entrada usando JwtSecurityTokenHandler.
string authHeader = "Bearer <token>"; // the Authorization header value
var jwt = new JwtSecurityTokenHandler().ReadJwtToken(token);
string tid = jwt.Claims.Where(c => c.Type == "tid").FirstOrDefault()?.Value;
string aud = jwt.Claims.Where(c => c.Type == "aud").FirstOrDefault()?.Value;
string appid = jwt.Claims.Where(c => c.Type == "appid").FirstOrDefault()?.Value;
if(tid != "<my tenant id>" || aud != "<my application id>" || appid != "bf04bdab-e06f-44f3-9821-d3af64fc93a9")
{
throw new Exception("the token is not authorized.");
}
Práticas de dados externos
Você reconhece que é responsável pela adesão a todas as leis e regulamentos aplicáveis, incluindo, sem limitação, leis de proteção de dados, restrições contratuais e/ou políticas relacionadas a conjuntos de dados fornecidos à Microsoft por meio do recurso Chamadas Externas do Fraud Protection. Além disso, você reconhece que o uso do Fraud Protection está sujeito a restrições de uso detalhadas no Contrato de Cliente da Microsoft, que afirma que você não pode usar o Fraud Protection (i) como o único fator para determinar se deve continuar com uma transação de pagamento; (II) como um fator para determinar o status financeiro, o histórico financeiro, a confiabilidade de crédito ou a qualificação para seguros, hospedagem ou emprego de qualquer pessoa; ou (III) para tomar decisões que geram efeitos legais ou afetam consideravelmente uma pessoa. Você também não está proibido de fornecer ou usar tipos de dados confidenciais ou altamente regulamentados em relação ao uso do recurso de chamadas externas do Fraud Protection. Reserve um tempo para revisar qualquer conjunto de dados ou tipos de dados antes de usá-los com o recurso de chamadas externas do Fraud Protection para garantir que você esteja em conformidade com esta disposição. A Microsoft também se reserva o direito de verificar se você cumpre essa provisão.