Chamadas externas
As chamadas externas permitem-lhe ingerir dados de APIs fora do Microsoft Dynamics 365 Proteção contra Fraude e, em seguida, utilizar esses dados para tomar decisões informadas em tempo real. Por exemplo, serviços de verificação de endereço e telefone de terceiros, ou seus próprios modelos de pontuação personalizados, podem fornecer informações críticas que ajudam a determinar o nível de risco para alguns eventos. Usando chamadas externas, você pode se conectar a qualquer ponto de extremidade de API, fazer uma solicitação para esse ponto de extremidade de dentro de sua regra, conforme necessário, e usar a resposta desse ponto de extremidade para tomar uma decisão.
Nota
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 saber sobre as seguintes limitações:
- Atualmente, a Proteção contra Fraude suporta apenas os seguintes métodos de autenticação: Anonymous e AAD.
- Atualmente, a Proteção contra Fraude suporta apenas os seguintes métodos HTTP: GET e POST.
Criar uma chamada externa
No portal Proteção contra fraudes, na navegação à esquerda, selecione Chamadas externas e, em seguida, selecione Nova chamada externa.
Revise e defina os seguintes campos conforme necessário.
Nome – Insira o nome que você usará para fazer referência à chamada externa de suas regras. O nome pode conter apenas números, letras e sublinhados. Não pode começar com um número.
Nota
Não é possível alterar o nome de uma chamada externa depois de usá-la em uma regra.
Descrição – Adicione uma descrição para ajudar sua equipe a identificar rapidamente a chamada externa.
Solicitação da Web – Selecione o método HTTP apropriado (GET ou POST) e insira o ponto de extremidade da API.
Nota
Somente pontos de extremidade HTTPS são suportados.
Ativar chamadas de aquecimento periódicas - Se o tráfego para o seu ponto de extremidade de chamada externa for muito baixo, a conexão pode ficar fria e pode 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 chamadas externas. Use a alternância para ativar chamadas de aquecimento. Você é obrigado a fornecer um URL GET Keep-alive válido. Assim como no ponto de extremidade primário, o ponto de extremidade keep-alive também deve passar no teste de conexão. Se você configurar sua chamada externa com chamadas de aquecimento habilitadas, quando o volume de tráfego cair muito, a Proteção contra Fraude fará automaticamente chamadas de aquecimento anônimas para o ponto de extremidade keep-alive usando apenas o método GET.
Nota
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 Ative 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.
Público - Se você selecionar o AAD como o método de autenticação, será solicitado que forneça um público. 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 de Proteção contra Fraude. Verifique se o público tem permissão para acessar a chamada/serviço externo. Para saber mais sobre como configurar a autenticação do Azure Ative 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 do Azure AD novo ou existente em seu locatário de assinatura do Fraud Protection. Gere um certificado no seu Cofre da Chave do Azure. O aplicativo Proteção contra Fraude deve ter acesso de leitura a este Cofre de Chaves do Azure. Carregue o certificado para este aplicativo do Azure AD. Para obter mais informações sobre como criar e gerenciar aplicativos do Azure AD, consulte Criar aplicativos do Azure Ative Directory.
URL do certificado – Forneça a URL do identificador de certificado do seu Cofre da Chave do Azure. Este é o mesmo certificado que você carregou para o aplicativo Azure AD na etapa anterior. Para obter mais informações sobre como gerar um certificado no Cofre da Chave do Azure, consulte Criando e mesclando uma solicitação de assinatura de certificado no Cofre da Chave do Azure
Adicionar parâmetro – Você pode usar parâmetros para passar dados da Proteção contra fraude para o endpoint da API. Dependendo do método HTTP selecionado, esses parâmetros são enviados para o 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. A Proteção contra Fraude usa esses valores de parâmetro para fazer uma chamada de exemplo para seu ponto de extremidade, antes da criação ou sempre que você selecionar Testar.
Nota
Todos os valores de parâmetros são interpretados como strings.
Solicitação de amostra – Forneça um exemplo da solicitação enviada para sua chamada externa. A solicitação deve refletir os nomes e valores de parâmetros especificados 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.
A solicitação de exemplo é usada para fazer uma chamada de amostra para seu ponto de extremidade, antes da criação ou sempre que você selecionar Testar.
Exemplo de resposta – Forneça um exemplo dos dados retornados em uma resposta bem-sucedida do seu ponto de extremidade da API. Esses dados devem estar no formato JSON (JavaScript Object Notation) e podem ser referenciados em suas regras. O exemplo que você fornece aqui é mostrado à medida que você cria regras.
Selecione Testar para inserir automaticamente uma resposta real da sua API neste campo.
Tempo limite – Especifique quanto tempo, em milissegundos, a solicitação deve esperar antes de atingir o tempo limite. Você deve especificar um número entre 1 e 1000.
Resposta padrão – Especifique a resposta padrão que deve ser retornada se sua solicitação falhar ou exceder o tempo limite especificado. O valor deve ser objeto JSON válido ou elemento JSON.
Opcional: para enviar uma solicitação de exemplo para seu ponto de extremidade da 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 a Proteção contra Fraude possa se conectar ao seu endpoint, teste a conexão a qualquer momento.
Para testar uma ligação enquanto está a criar uma nova chamada externa ou a editar uma chamada externa existente, defina todos os campos obrigatórios e, em seguida, selecione Testar.
A Proteção contra Fraude usa o ponto de extremidade e os parâmetros que você forneceu para enviar uma solicitação para sua chamada externa.
- Se a Proteção contra fraude 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 visualizar a resposta completa, selecione Ver detalhes da resposta.
- Se a Proteção contra fraude não conseguir atingir o ponto de extremidade de destino ou se não receber uma resposta antes do tempo limite especificado, uma barra de mensagens vermelha aparecerá na parte superior do painel e mostrará o erro encontrado. Para ver mais informações sobre o erro, selecione Ver detalhes do erro.
Monitorar chamadas externas
Monitorizar chamadas externas no portal de Proteção contra Fraude
A Proteção contra fraude mostra um bloco que contém três métricas para cada chamada externa que você definir:
- 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 que são feitas.
Os números e gráficos mostrados neste bloco incluem apenas dados para o período de tempo selecionado na lista suspensa no canto superior direito da página.
Nota
As métricas são mostradas somente quando sua chamada externa é usada em uma regra ativa.
Para se aprofundar nos dados sobre sua chamada externa, selecione Desempenho no canto direito do bloco.
A Proteção contra fraude mostra uma nova página com uma visão mais detalhada das métricas.
Para visualizar métricas de qualquer período nos últimos três meses, ajuste a configuração Intervalo de datas na parte superior da página.
Além das três métricas descritas anteriormente, um gráfico de erros é mostrado. 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ê pode ver os seguintes erros:
- ID do aplicativo inválido – O ID do aplicativo que foi fornecido não existe no seu locatário ou não é válido.
- Falha do AAD – O token do Azure AD não pôde ser recuperado.
- Definição não encontrada – A chamada externa foi excluída, mas ainda é referenciada em uma regra.
- Tempo limite – A solicitação para o destino levou mais tempo do que o tempo limite especificado.
- Falha de comunicação – Nenhuma conexão pode ser feita com o destino devido a um problema de rede ou porque o destino não está disponível.
- Disjuntor – Se a chamada externa tiver falhado continuamente e tiver excedido um determinado limite, todas as chamadas adicionais serão suspensas por um curto intervalo.
- Falha desconhecida – Ocorreu uma falha de Dynamics 365 interna.
Usar o rastreamento de eventos para monitorar chamadas externas
Você pode usar o recurso de rastreamento de eventos da Proteção contra Fraude para encaminhar eventos relacionados às suas chamadas externas para suas próprias instâncias dos Hubs de Eventos do Azure ou do Armazenamento de Blobs do Azure. No portal de Proteção contra Fraudes, na página Rastreamento de Eventos, você pode se inscrever nos dois eventos a seguir relacionados a chamadas externas:
- FraudProtection.Monitoring.ExternalCalls
- FraudProtection.Errors.ExternalCalls
Sempre que uma solicitação é feita para uma chamada externa, um evento é enviado para o namespace FraudProtection.Monitoring.ExternalCalls. A carga útil do evento inclui informações sobre a latência da chamada, o status da solicitação e a regra e a cláusula a partir da qual a solicitação foi acionada.
Quando uma chamada externa falha, um evento é enviado para o namespace FraudProtection.Errors.ExternalCalls. A carga útil do evento inclui a solicitação de URI e o corpo que foram enviados para a chamada externa e a resposta recebida.
Para obter mais informações sobre rastreamento de eventos, como se inscrever em eventos e o que você pode fazer com eventos, consulte Rastreamento de eventos.
Para obter informações sobre como integrar esses dados aos fluxos de trabalho da sua própria organização e configurar monitoramento, alertas e relatórios personalizados, consulte Extensibilidade via Hubs de Eventos.
Gerenciar chamadas externas
Para editar uma chamada externa existente, selecione Editar no cabeçalho do cartão.
Nota
Não é possível alterar o nome e os parâmetros de uma chamada externa depois de usá-la em uma regra.
Para eliminar uma chamada externa existente, selecione as reticências (...) e, em seguida, selecione Eliminar.
Nota
Não é possível excluir uma chamada externa depois que ela é referenciada em uma regra.
Para visualizar métricas de desempenho detalhadas para uma chamada externa, selecione Desempenho.
Para testar se a Proteção contra Fraude ainda pode se conectar à sua chamada externa, selecione as reticências (...) e, em seguida, selecione Testar conexão.
Usar uma chamada externa em regras
Para usar suas chamadas externas para tomar decisões, consulte-as a partir de suas regras.
Por exemplo, para fazer referência a uma chamada externa chamada myCall na 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 o idioma das regras e como você pode usar chamadas externas em regras, consulte o Guia de referência de idioma.
Nota
Se chamadas externas forem usadas em uma regra, a latência da regra poderá aumentar.
Compreender a autenticação e a autorização
Para garantir que os dados sejam acessados com segurança, as APIs geralmente autenticam o remetente de uma solicitação para verificar se eles têm permissão para acessar os dados. As chamadas externas no Fraud Protection suportam dois métodos de autenticação: Anonymous 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 seu ponto de extremidade usa uma chave de API, configure o par chave-valor como parte da URL de solicitação inserida no campo Solicitação da Web. O ponto de extremidade de destino pode então validar se a chave de API da URL de solicitação é permitida e, em seguida, decidir 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 JSON Web Token (JWT) emitido pelo Azure AD. Para obter informações sobre JWTs, consulte Tokens de acesso à plataforma de identidade da Microsoft. A Proteção contra Fraude acrescenta o valor do token ao texto "Portador" no formato necessário no cabeçalho da solicitação de autorização, conforme mostrado aqui:
Token ao portador <>
Declarações de token
A tabela a seguir lista as declarações que você pode esperar em tokens ao portador emitidos pela Proteção contra fraude.
| Nome | Afirmação | Description |
|---|---|---|
| ID de Inquilino do | TID | Esta declaração identifica o ID de locatário do Azure da assinatura associada à sua conta de Proteção contra Fraude. Para obter informações sobre como encontrar seu ID de locatário no portal de Proteção contra Fraude, consulte IDs e informações necessárias. Para obter informações sobre como localizar sua ID de locatário no portal do Azure, consulte Como localizar sua ID de locatário do Azure Ative Directory. |
| Audiência | aud | Esta declaração identifica o destinatário pretendido do token. O valor reflete exatamente o ID do aplicativo que você forneceu quando configurou sua chamada externa no portal de Proteção contra Fraude. |
| ID da aplicação | Appid | Esta alegação é o ID do aplicativo da Fraud Protection: * bf04bdab-e06f-44f3-9821-d3af64fc93a9*. Esta ID pertence exclusivamente à Proteção contra Fraude e apenas a Microsoft pode solicitar um token em seu nome. |
Quando sua API recebe um token, ela deve abri-lo e validar se cada uma das declarações anteriores corresponde à sua descrição.
Aqui está 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 por aderir 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 da Proteção contra Fraudes. Além disso, reconhece que a sua utilização da Proteção contra Fraude está sujeita a restrições de utilização detalhadas no Contrato de Cliente da Microsoft, que estabelece que não pode utilizar a Proteção contra Fraude (i) como o único fator para determinar se deve prosseguir com uma transação de pagamento; (ii) como um fator para determinar a situação financeira, histórico financeiro, solvabilidade ou elegibilidade de qualquer pessoa para seguro, habitação ou emprego; ou (iii) tomar decisões que produzam efeitos legais ou afetem significativamente uma pessoa. Você também está proibido de fornecer ou usar tipos de dados confidenciais ou altamente regulamentados em conexão com o uso do recurso de chamadas externas da Proteção contra fraude. Reserve um tempo para revisar qualquer conjunto de dados ou tipos de dados antes de usá-los com o recurso de chamadas externas da Proteção contra Fraude para garantir que você esteja em conformidade com esta disposição. A Microsoft também se reserva o direito de verificar se você está em conformidade com esta disposição.