Integrar APIs de proteção da conta
Para aproveitar o conjunto completo de recursos do Microsoft Dynamics 365 Fraud Protection, envie seus dados de transação para as APIs em tempo real. Na experiência de avaliação, é possível analisar os resultados do uso do Fraud Protection. Na experiência de proteção, você também pode respeitar as decisões que são baseadas nas regras que configurou.
Dependendo de como optar por usar o Fraud Protection, você poderá usar APIs de proteção de conta diferentes: Por exemplo, AccountCreation, AccountLogin, AccountCreationStatus, AccountLoginStatus, AccountUpdate e Label.
Para obter informações sobre todos os eventos com suporte, consulte API do Dynamics 365 Fraud Protection.
Configurar
Entrar
Importante
Para concluir a integração inicial, você deve ser um Administrador Global em seu locatário do Microsoft Azure.
Para entrar no Fraud Protection:
Acesse o Portal do Fraud Protection, faça logon e aceite os termos e condições se for solicitado a aceitá-los.
Esta etapa garante que o Fraud Protection esteja configurado corretamente em seu locatário do Azure. (Talvez você já tenha concluído esta etapa da produção durante a inscrição inicial.)
Criar aplicativos do Microsoft Entra
Importante
Para concluir esta etapa, você deve ser um administrador de aplicativos, administrador de aplicativos em nuvem ou administrador global em seu locatário do Azure.
Para adquirir os tokens necessários para chamar as APIs, você deve usar aplicativos do Microsoft Entra. Você pode configurá-los usando a página APIs em tempo real no Fraud Protection.
Para configurar aplicativos do Microsoft Entra:
No painel de navegação esquerdo, selecione Configuração e depois selecione APIs em tempo real.
Preencha os campos para criar seu aplicativo. Os seguintes campos são obrigatórios:
- Nome de exibição do aplicativo — insira um nome descritivo para o aplicativo. O tamanho máximo é de 93 caracteres.
- Ambiente — selecione o ponto de extremidade de produção.
- Método de autenticação — selecione um certificado ou segredo (senha) a ser usado para a autenticação. Se você selecionar Certificado, selecione Escolher arquivo para carregar a chave pública. Quando adquirir tokens, você precisará da chave privada correspondente. Se você selecionar Segredo, uma senha será gerada após a criação do aplicativo.
Quando terminar de preencher os campos, selecione Criar aplicativo.
A página de confirmação resume o nome e a ID do aplicativo e a impressão digital do certificado ou segredo, dependendo do método de autenticação selecionado.
Importante
Salve as informações sobre impressão digital do certificado ou segredo para futura referência. O segredo será mostrado somente uma vez.
Você poderá criar quantos aplicativos forem necessários para executar chamadas de API em seus ambientes de produção.
Para criar outro aplicativo:
- Selecione Criar outro aplicativo.
- Preencha os campos para criar seu aplicativo e selecione Criar aplicativo.
Gerenciar aplicativos existentes do Microsoft Entra
Depois de criar seus aplicativos do Microsoft Entra, você pode gerenciá-los por meio do [portal do Azure](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Para obter mais informações, consulte o site de documentação do Azure.
Chamar as APIs em tempo real do Fraud Protection
Use as informações desta seção para integrar seus sistemas ao Fraud Protection.
IDs e informações necessárias
- Ponto de extremidade da API — o URI de seu ambiente aparece no bloco Informações da conta no painel do Fraud Protection.
- ID do Diretório (locatário) — A ID do diretório é o GUID (Identificador Global Exclusivo) do domínio de um locatário no Azure. Ele aparecerá no portal do Azure e no bloco Informações da conta no painel do Fraud Protection.
- ID do aplicativo (cliente) – A ID do aplicativo identifica o aplicativo Microsoft Entra que você criou para chamar APIs. Você pode encontrar essa ID na página confirmação que será exibida depois que você selecionar Criar aplicativo na página APIs em tempo real. Você também poderá encontrá-la posteriormente, em Registros de aplicativos no portal do Azure. Haverá uma ID para cada aplicativo criado.
- Impressão digital do certificado ou segredo — você pode encontrar a impressão digital do certificado ou o segredo na página de confirmação que será exibida depois que você selecionar Criar aplicativo na página APIs em tempo real.
- ID da Instância – a ID da instância é o identificador global exclusivo (GUID) do seu ambiente no Fraud Protection. Ela aparece no bloco Integração no painel do Fraud Protection.
Gerar um token de acesso
Você deve gerar esse token e fornecê-lo com cada chamada de API. Observe que os tokens de acesso têm uma vida útil limitada. Recomendamos que você o armazene em cache e reutilize cada token de acesso até a hora de obter um novo token de acesso.
Os exemplos de código C# a seguir fornecem exemplos que mostram como adquirir um token usando seu certificado ou segredo. Substitua os espaços reservados por suas próprias informações.
Impressão digital do certificado
public async Task<string> AcquireTokenWithCertificateAsync()
{
var x509Cert = CertificateUtility.GetByThumbprint("<Certificate thumbprint>");
var clientAssertion = new ClientAssertionCertificate("<Client ID>", x509Cert);
var context = new AuthenticationContext("<Authority URL. Typically https://login.microsoftonline.com/[Directory_ID]>");
var authenticationResult = await context.AcquireTokenAsync("<API endpoint>", clientAssertion);
return authenticationResult.AccessToken;
}
Segredo
public async Task<string> AcquireTokenWithSecretAsync()
{
var clientAssertion = new ClientCredential("<Client ID>", "<Client secret>");
var context = new AuthenticationContext("<Authority URL. Typically https://login.microsoftonline.com/[Directory_ID]>");
var authenticationResult = await context.AcquireTokenAsync("<API endpoint>", clientAssertion);
return authenticationResult.AccessToken;
}
Resposta
Em segundo plano, o código anterior gera uma solicitação HTTP e recebe uma resposta que se assemelha ao exemplo a seguir.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: <date>
Content-Length: <content length>
{
"token_type":"Bearer",
"expires_in":"3599",
"ext_expires_in":"3599",
"expires_on":"<date timestamp>",
"not_before":"<date timestamp>",
"resource":"https://api.dfp.dynamics.com",
"access_token":"<your access token; e.g.: eyJ0eXA...NFLCQ>"
}
Para obter mais informações, consulte a documentação do Azure:
- Usar declaração de cliente para obter tokens de acesso do Microsoft Entra ID
- Armazenar tokens de acesso em cache
Chamar as APIs
Para chamar as APIs, siga as etapas a seguir.
Passe os seguintes cabeçalhos HTTP necessários em cada solicitação.
Nome do cabeçalho Valor do cabeçalho Autorização Use o seguinte formato para este cabeçalho: Bearer accesstoken, onde accesstoken é o token retornado pelo Microsoft Entra ID. x-ms-correlation-id Envie um novo valor de GUID para cada conjunto de chamadas de API que são feitas juntas. x-ms-dfpenvid Envie o valor do GUID da sua ID de Instância. Gere uma carga útil baseada em evento. Preencha os dados do evento com as informações relevantes do seu sistema. Para obter informações sobre todos os eventos com suporte, consulte API do Dynamics 365 Fraud Protection.
Combine o cabeçalho (que inclui o token de acesso) e a carga e envie-os para o ponto de extremidade do Fraud Protection.
Observação
Se você criar um novo ambiente, inclua a ID do ambiente no cabeçalho da API durante a integração, para que as transações possam ser roteadas corretamente.
Exibir o aplicativo de exemplo
Para obter referências adicionais, consulte o aplicativo comercial de exemplo e a documentação do desenvolvedor que o acompanha. O aplicativo de exemplo fornece um exemplo que mostra como chamar APIs do Fraud Protection em tempo real. A documentação do aplicativo de exemplo está vinculada ao código de exemplo real sempre que essas vinculações são possíveis. Caso contrário, os códigos de exemplo estarão incluídos diretamente na documentação.
Para obter informações sobre como configurar o site de exemplo para que possa usá-lo, consulte Configurar o site de exemplo.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de