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, ele age como uma fonte de dados que permite enviar dados e receber 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.

Nota

Para obter mais informações sobre como alterar a configuração Compartilhamento de uma avaliação de Privada 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 Privada: Ambiente Y = Ambiente X

Para avaliação compartilhada: Ambiente Y = Qualquer ambiente raiz dentro do 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. À semelhança das 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 certa 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 Proteção contra fraudes, no painel de navegação esquerdo, selecione Avaliações externas e, 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 – No menu suspenso 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 segmentar.

Nota

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 – Digite o nome que você usará para fazer referência à avaliação 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 avaliação externa depois de 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

Nota

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 de 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, consulte-as a partir de suas regras. Por exemplo, para fazer referência a uma avaliação externa, chamada myAssessment, em sua regra, use a seguinte sintaxe:

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

No exemplo acima, $baseInput = @@mapeará todos os campos necessários para a avaliação compartilhada/externa da carga útil da avaliação de chamada. Você também pode mapear campos específicos apenas. Você também pode definir quais ações deseja que a regra execute com base nas informações que ela receberá de volta da chamada 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 Usar uma regra de avaliação externa ou copiar/colar o FQL de exemplo da página de 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 são marcados como tal no código.

Aqui está outro exemplo de FQL para chamar a API de avaliação de 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 Request, 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.

A seguir está um exemplo de uma regra usando o objeto diagnostics 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 linguagem.

Nota

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

Monitorizar avaliações 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 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 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 avaliação externa é usada em uma regra ativa.

• Para se aprofundar nos dados sobre sua avaliação 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 também é mostrado. Este gráfico mostra o número de erros por tipo de erro e código. Para visualizar 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ê pode ver os seguintes erros:

• ID de aplicativo inválido – A ID do aplicativo que foi fornecida não existe no seu locatário ou 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 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 falhou continuamente e excedeu um determinado limite, todas as chamadas adicionais são suspensas por um curto intervalo.
• Falha desconhecida – Ocorreu uma falha interna do Dynamics 365.