Avaliações externas

A avaliação externa é um mecanismo para chamar uma avaliação a partir de qualquer outra avaliação. Uma avaliação externa não é uma avaliação em si. Em vez disso, ela atua como uma fonte de dados que permite que você envie dados e receba uma resposta de uma avaliação de destino. Uma avaliação pode ter uma das duas configurações de compartilhamento possíveis:

• Privado: acessível apenas no ambiente raiz da avaliação.
• Compartilhado: acessível em todos os ambientes do locatário.

As avaliações externas podem apontar para qualquer avaliação privada disponível no mesmo ambiente raiz ou qualquer avaliação compartilhada disponível em qualquer ambiente raiz do locatário.

Observação

Para obter mais informações sobre como alterar a configuração de Compartilhamento de uma avaliação de Particular para Compartilhada ou Compartilhada para Privada, consulte Visão geral da configuração da avaliação.

Depois de configurar uma avaliação externa, ela pode ser chamada por meio de uma regra de qualquer avaliação nesse ambiente.

Para avaliação particular: ambiente Y = ambiente X

Para avaliação compartilhada: ambiente Y = qualquer ambiente raiz no mesmo locatário

Uma avaliação de chamada refere-se a qualquer avaliação que chame uma avaliação privada ou compartilhada por meio de uma avaliação externa. A avaliação de chamada deve ter uma regra de avaliação externa configurada. Quando a condição da regra for atendida, a regra chamará a avaliação externa e executará as ações configuradas. Semelhante às chamadas externas, as avaliações externas não são herdadas pelas crianças. Para usar uma avaliação externa em uma regra, você deve configurar a avaliação externa no ambiente do qual deseja chamá-la.

Criar uma avaliação externa

Para criar uma avaliação externa, primeiro verifique se você tem a permissão correta para executar essa operação. Para obter mais informações sobre funções e permissões de usuário, consulte Funções e acesso de usuário

1. No portal do Fraud Protection, na navegação à esquerda, selecione Avaliações Externase, em seguida, selecione + Nova avaliação externa.
2. Na página Nova avaliação externa, defina os seguintes campos:

• Avaliação de destino a ser chamada – Na lista suspensa, você pode ver todas as avaliações privadas, configuradas no mesmo ambiente raiz, bem como quaisquer avaliações compartilhadas disponíveis, configuradas em qualquer ambiente raiz do mesmo locatário. Selecione a avaliação que deseja usar como destino.

Anotação

Se a avaliação compartilhada para a qual você deseja apontar sua avaliação externa não estiver sendo exibida na lista suspensa, verifique a configuração Compartilhamento da avaliação e verifique se ela está definida como Compartilhada. Para saber mais sobre como definir a configuração de Compartilhamento, consulte Visão geral da configuração de avaliação.

• Nome – insira o nome que será usado para referenciar a avaliação externa em suas regras. O nome só pode conter números, letras e sublinhados. Ele não pode começar com um número.

Anotação

Não é possível alterar o nome de uma avaliação externa após usá-la em uma regra.

• Descrição – adicione uma descrição para ajudar sua equipe a identificar rapidamente a avaliação externa.
• API para visualização – selecione a API para a qual você deseja visualizar o código de exemplo. O código de exemplo é o FQL que você pode usar em uma regra para chamar essa avaliação compartilhada

Observação

Você pode usar a avaliação externa para chamar a API de avaliação, observação ou rótulo da avaliação compartilhada ou privada para a qual ela aponta.

• Resposta de amostra – Esta seção contém a resposta de amostra esperada da avaliação de destino. As informações exibidas são fornecidas manualmente pelo administrador da avaliação de destino e são usadas para habilitar descrições (dicas de ferramentas) e sugestões para preenchimento automático quando a avaliação é referenciada em uma regra.

3. Quando terminar de definir os campos obrigatórios, selecione Criar.

Chamar uma avaliação externa

Para usar suas avaliações externas, faça referência a elas em suas regras. Por exemplo, para referenciar uma avaliação externa, chamada myAssessment, use a seguinte sintaxe na sua regra:

Assessments.myAssessment.Evaluate($baseInput = @@)

No exemplo acima, $baseInput = @@ mapeará todos os campos necessários à avaliação compartilhada/externa a partir do conteúdo da chamada da avaliação. Você também pode mapear somente campos específicos. Você também pode definir as ações que deseja que a regra execute com base nas informações que ela receberá de volta da chamada de avaliação externa.

Por exemplo,

LET $card = {
  number: 12345,
  expy: "2023-03-10".ToDateTime()
}
LET $response = Assessments.MicroTx.evaluate(card = $card, user = @@"user")
OBSERVE Output(decision = $response.decisionDetails.merchantRuleDecision)

Você pode configurar uma regra para chamar a avaliação externa usando o modelo de regra Usar uma avaliação externa ou copiar/colar o FQL de exemplo da página da avaliação externa. Certifique-se de usar o código de exemplo para a API (avaliar, observar, rotular) que você deseja chamar. O código de exemplo mostrará todos os campos que podem ser enviados para a avaliação compartilhada. Os campos obrigatórios serão marcados como tal no código.

Veja outro FQL de exemplo para chamar a API de avaliação da avaliação externa chamada ExtAssessment1:

LET $customUser = {
    id: "userId123456",
    username: "johnsmith2",
    firstName: "John",
    lastName: "Smith",
    email: "johnsmith2@gmail.com",
    address: {
        street1: "0123 Bechtelar Loop",
        city: "Kubtown",
        state: "SC",
        zipCode: "44329",
        countryRegion: "US"
    }
}

LET $result = Assessments.ExtAssessment1.Evaluate(
    user = $customUser,
    specialConsideration = true)
OBSERVE Output(Result = $result)

Você também pode acessar o objeto de diagnóstico em regras, o que permite descobrir informações importantes de diagnóstico e depuração a partir da resposta de uma avaliação externa. O objeto de diagnóstico contém a carga útil da solicitação, o código HttpStatus, a mensagem de erro e a latência. O objeto de diagnóstico deve ser criado primeiro usando seu método de extensão correspondente, ". GetDiagnostics()", antes que os campos do objeto possam ser usados nas regras.

Veja a seguir um exemplo de uma regra usando o objeto de diagnóstico na resposta de uma avaliação externa chamada ExtAssessment2:

LET $result = Assessments.ExtAssessment2.evaluate($baseInput =@@)
LET $diagnostics = $result.GetDiagnostics()
RETURN Approve(), Output (Diagnostics = $diagnostics)
WHEN $diagnostics.httpStatusCode==200

Chamadas externas e avaliações externas podem exigir objetos estruturados complexos como parte de seu esquema de solicitação. Para obter mais informações sobre como usar matrizes e objetos JSON, consulte o Guia de referência de idioma.

Observação

As Avaliações Externas também podem ser referenciadas em Funções. Para obter mais informações, consulte Funções.

Monitorar avaliações externas no portal de Proteção contra Fraudes

O Fraud Protection mostra um bloco que contém três métricas para cada avaliação 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 foram 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.

Anotação

As métricas serão mostradas somente quando a avaliação externa for usada em uma regra ativa.

• Para aprofundar-se nos dados sobre a avaliação 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 Erros também será exibido. Este gráfico mostra o número de erros por tipo de erro e código. Para exibir a contagem 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 Microsoft Entra – O token do Microsoft Entra 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 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 falhar continuamente e exceder um determinado limite, todas as chamadas adicionais serão suspensas por um curto intervalo.
• Falha desconhecida – ocorreu uma falha interna do Dynamics 365.