Compartilhar via

Guia de Início Rápido: fazer uma chamada à API autenticada

  • Artigo

Este artigo ajuda você a criar uma solicitação autenticada para o serviço do Recomendações Inteligentes e ver os resultados.

Visão geral

Para fazer uma solicitação de API bem-sucedida, você precisa preparar as seguintes informações:

  • ID de locatário do Microsoft Entra ID
  • ID do cliente do aplicativo do chamador
  • Valor do segredo do aplicativo
  • A consulta HTTP usando a conta do Recomendações Inteligentes que veicula o URL do ponto de extremidade composta por caminho/parâmetros de consulta válidos, conforme descrito na API do Recomendações Inteligentes.

Para obter ajuda para localizar essas informações, continue lendo.

Se você tiver essas informações preparadas, pule para a seção Criar a solicitação de API deste Guia de Início Rápido.

Pré-requisitos

Antes de começar, verifique se você tem:

Observação

Depois que o serviço for provisionado com êxito, pode levar até um dia para que o treinamento do modelo de IA-ML processe os dados de entrada e produza listas classificadas. Se você acabou de provisionar sua primeira conta do Recomendações Inteligentes, convém aguardar antes de continuar.

Etapa 1: Criar o URL do ponto de extremidade

Todas as contas do Recomendações Inteligentes requer pelo menos um ponto de extremidade de serviço para atender às solicitações. Um ponto de extremidade de serviço fornece um URL exclusivo para chamar o serviço.

Para criar uma solicitação de API adequada, localize o URL do ponto de extremidade de serviço usando sua conta do portal do Azure:

  1. Entre no portal do Azure.

  2. Navegue até Contas do Recomendações Inteligentes.

  3. Selecione a conta que você quer consultar.

  4. Na seção Componentes do menu, selecione Pontos de extremidade de serviço.

  5. Selecione o ponto de extremidade de serviço que você quer usar.

  6. Localize o URL nas propriedades do recurso do ponto de extremidade conforme mostrado:

    Localize o URL do ponto de extremidade de serviço nas propriedades do recurso do ponto de extremidade.

O URL é estruturado da seguinte maneira:

https://{ir-account-name}-{service-endpoint-name}.mir.prod.reco.microsoft.com/

Etapa 2: Configurar um aplicativo cliente

O Recomendações Inteligentes requer autenticação OAuth2. Determine (ou crie) o aplicativo Microsoft Entra ID do qual chamar o ponto de extremidade de serviço com autenticação. Todas as chamadas não autenticadas falham com um erro.

  1. Entre no portal do Azure.

  2. Acesse Microsoft Entra ID.

  3. Acesse Registros de aplicativo.

  4. Selecione um aplicativo existente ou crie um novo.

  5. Quando o aplicativo estiver pronto, localize a ID do cliente e a ID do locatário nas propriedades do aplicativo:

    Localize a ID do cliente e a ID do locatário nas propriedades do aplicativo Microsoft Entra ID.

  6. Anote a ID do cliente e a ID do locatário. Esses valores são usados para criar a solicitação de API.

Adicionar a identidade ou as identidades permitidas à conta do Recomendações Inteligentes

Antes de continuar, você deve adicionar a identidade à lista autenticada em sua conta do Recomendações Inteligentes.

  1. Entre no portal do Azure.
  2. Navegue até Contas do Recomendações Inteligentes.
  3. Selecione a conta que você quer consultar.
  4. No menu, selecione Autenticações do ponto de extremidade.
  5. Adicione a nova ID da entidade de segurança do aplicativo (a ID da entidade de segurança é a mesma que a ID do cliente, que você encontrou anteriormente).
  6. Altere o tipo principal para o "Aplicativo".

Observação

A atualização dessas configurações pode levar até 15 minutos.

Etapa 3: Configurar a autenticação

A última etapa é configurar o mecanismo de autenticação. Você pode usar um segredo ou um certificado. Neste guia de início rápido, você vê como criar um segredo.

  1. No painel de navegação à esquerda, selecione Certificados e segredos.
  2. Selecione Novo segredo do cliente. Esse valor de segredo é particular e deve ser armazenado em um local seguro, pois você precisará dele na próxima etapa.

Observação

Você só pode copiar o valor do segredo logo após a criação, conforme mostrado: Copie o segredo do aplicativo.

Agora que você preparou as informações necessárias, já pode criar uma solicitação de API e chamar o serviço do Recomendações Inteligentes.

Criar a solicitação de API

A próxima seção fornece duas maneiras de chamar a API de Recomendações Inteligentes com ferramentas de API REST. Para usar outro aplicativo para chamar o ponto de extremidade do Recomendações Inteligentes, verifique se você está usando uma ferramenta da API REST compatível com a autenticação OAuth2.

Neste Guia de Início Rápido, você percorrer como configurar uma solicitação de API para recuperar uma lista popular de itens com o código Insomnia e C#.

Antes de continuar, verifique se você possui todos estes pré-requisitos:

  1. ID de locatário do Microsoft Entra ID
  2. ID do cliente do aplicativo do chamador
  3. Valor do segredo do aplicativo
  4. A consulta HTTP usando a conta do Recomendações Inteligentes que veicula o URL do ponto de extremidade composta por caminho/parâmetros de consulta válidos, conforme descrito na API do Recomendações Inteligentes

Observação

Na solicitação de exemplo a seguir, estamos usando o nome da conta irtest e o ponto de extremidade de serviço serving01.

https://irtest-serving01.mir.prod.reco.microsoft.com/Reco/V1.0/Popular

Chamar o ponto de extremidade com o Explorador de resultados

IMPORTANTE A partir de abril de 2023, o site do Portal de IR e a ferramenta Gerenciador de Resultados ficaram obsoletos e não estão mais em uso. Para ver os resultados, use uma das opções nas seguintes seções:

Chamar o ponto de extremidade com o Insomnia

Você pode usar o Insomnia ou uma ferramenta da API REST semelhante que ofereça suporte à autenticação OAuth2 para enviar solicitações de teste para um ponto de extremidade de Recomendações Inteligentes.

Para obter mais detalhes, consulte Usar Insomnia com a API Web do Dataverse

Processo de autenticação

  1. Na seção Introdução, selecione Criar uma solicitação.

  2. Navegue até a guia Autorização do criador de solicitações e configure-a com os seguintes valores:

    • Definir o tipo como OAuth 2.0
    • Defina Adicionar Cabeçalhos de Autorização como Cabeçalhos da Solicitação
    • Crie um novo token com um nome de token.
    • Tipo de concessão = Credenciais do cliente
    • URL do token de acesso = https://login.microsoftonline.com/<callerTenantID>/oauth2/v2.0/token
    • ID do Cliente = <yourAppClientID>
    • Segredo do Cliente = <yourAppSecretValue>
    • Escopo = <URL DO SEU PONTO DE EXTREMIDADE>/.default
    • Mantenha a autenticação do cliente definida como Enviar como cabeçalho de autenticação básico

    Veja como fica a aparência antes da geração do token:

    Exemplo de um formulário de autorização preenchido.

  3. Role a página até encontrar o botão Obter Novo Token de Acesso. Se a configuração estiver correta e você selecionar o botão, será aberta uma nova janela com um token viável.

  4. Selecione Usar token.

    Exemplo de um token de acesso adequado.

Postar a solicitação

Agora que você está autenticado, pode postar a solicitação real.

  1. Poste sua solicitação e selecione Enviar. Consulte nosso Guia de amostra de solicitações para obter uma lista de solicitações adicionais de API pré-configuradas para você testar.

  2. A resposta JSON aparece na parte inferior da tela:

    Exemplo de resultados retornados ao fazer uma solicitação de API popular.

Observação

Uma resposta bem-sucedida retornará uma lista classificada de itens na seção Itens da resposta JSON. Para este cenário, a ID de item mais popular é 712. Você pode ver a lista completa de Códigos de Status da API aqui.

Chamar o ponto de extremidade com o código C#

Para fazer uma chamada bem-sucedida para o ponto de extremidade do Recomendações Inteligentes usando C#, prepare as seguintes informações:

  1. ID de locatário do Microsoft Entra ID
  2. ID do cliente do aplicativo do chamador
  3. Valor do segredo do aplicativo
  4. A consulta HTTP usando a conta do Recomendações Inteligentes que veicula o URL do ponto de extremidade composta por caminho/parâmetros de consulta válidos, conforme descrito na especificação da API do Recomendações Inteligentes

Em seguida, copie o código de exemplo dado, atualize os campos relevantes e execute-o.

public static async Task CallIRApiAsync()
{
    // *************************************************************************
    // The code depends on the Microsoft.Identity.Client library
    // Please note the code sections that have to be modified below  
    // *************************************************************************

    // Recommendations AAD app ID
    var scope = "<YOUR ENDPOINT URL>";

    // Your client AAD app ID
    var callerAadAppId = "<YOUR AAD APP ID>";

    // AAD Tenant ID
    var callerAadTenantId = "<YOUR AAD TENANT ID>";

    var token = await AcquireTokenWithSecret(callerAadAppId, callerAadTenantId, scope);
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Authorization  = AuthenticationHeaderValue.Parse(token.CreateAuthorizationHeader());

    // **************************************************
    // and now, use httpClient to execute IR requests..
    // **************************************************
}

public static Task<AuthenticationResult> AcquireTokenWithSecret ( 
               string callerAadAppId, string callerTenantId, string scope )
{   
    // The below example uses a secret to authenticate to AAD
    // An alternative certificate-based method can be used instead:
    // replace: "WithClientCert(string secret)" ==> "WithCertificate(X509Certificate certificate)"

    var secret = "<YOUR AAD APP SECRET>";
    var app = ConfidentialClientApplicationBuilder.Create(callerAadAppId).WithAuthority($"https://login.microsoftonline.com/{callerTenantId}").WithClientSecret(secret).Build();
    var scopes = new[] { $"{scope}/.default" }; 
    return app.AcquireTokenForClient(scopes).ExecuteAsync(CancellationToken.None); }
}

Uma resposta bem-sucedida contém uma lista classificada de itens recomendados com base no cenário na seção Itens. Para este cenário, a ID de item mais popular é 712. Você pode ver a lista completa de Códigos de Status da API aqui.

Chamada do ponto de extremidade com o Aprendizado de Máquina do Azure

Para fazer solicitações de API para o serviço de Recomendações Inteligentes usando o Aprendizado de Máquina do Azure, você pode usar este Jupyter Notebook do Recomendador de Varejo. Como um bônus adicional, o notebook também inclui etapas para combinar as Recomendações Inteligentes com o Personalizador do Azure! Consulte: Jupyter Notebook do Recomendador de Varejo.

Confira também

Referência de API do Recomendações Inteligente
Códigos de Status da API
Guia de Início Rápido: configurar e executar o Recomendações Inteligentes com dados de exemplo
Visão geral da implantação
Usar contratos de dados para compartilhar dados