Partilhar via

Guia de início rápido: Faça uma chamada à API autenticada

  • Artigo

Este artigo ajuda-o a construir um pedido autenticado ao serviço Intelligent Recommendations e a ver resultados.

Descrição geral

Para fazer um pedido de API com êxito, precisa de preparar as seguintes informações:

  • ID do inquilino do ID do Microsoft Entra
  • ID de cliente da aplicação do chamador
  • Valor do segredo da aplicação
  • A consulta HTTP que utiliza o URL do ponto final de entrega da conta do Intelligent Recommendations composta por caminho de consulta/parâmetros válidos, conforme descrito na API Intelligent Recommendations.

Para ajuda com a localização destas informações, continue a ler.

Se tiver essas informações preparadas, poderá passar para a secção Construir o pedido de API deste guia de início rápido.

Pré-requisitos

Antes de começar, certifique-se de que tem:

Nota

Após o serviço ter sido aprovisionado com êxito, poderá demorar até um dia para que a preparação do modelo de IA-ML processe os dados de entrada e produza listas classificadas. Se tiver acabado de aprovisionar a primeira conta do Intelligent Recommendations, poderá querer aguardar antes de continuar.

Passo 1: Criar o URL de ponto final

Todas as contas do Intelligent Recommendations requer, pelo menos, um ponto final de serviço para entregar pedidos. Um ponto final de serviço fornece um URL exclusivo para chamar para o serviço.

Para criar um pedido de API adequado, localize o URL do ponto final de serviço utilizando a sua conta de portal do Azure:

  1. Inicie sessão no portal do Azure.

  2. Navegue para Contas do Intelligent Recommendations.

  3. Selecione a conta que pretende consultar.

  4. A partir da secção Componentes do menu, selecione Pontos Finais de Serviço.

  5. Selecione o ponto final de serviço que pretende utilizar.

  6. Localize o URL nas propriedades do recurso do ponto final, conforme mostrado:

    Localizar o URL do ponto final de serviço sob as propriedades do recurso do ponto final.

O URL é estruturado da seguinte forma:

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

Passo 2: Configurar uma aplicação cliente

O Intelligent Recommendations requer uma autenticação OAuth2. Determine (ou crie) a aplicação ID do Microsoft Entra a partir da qual o ponto final de serviço com autenticação. Todas as chamadas não autenticadas falham com um erro.

  1. Inicie sessão no portal do Azure.

  2. Aceda ao ID do Microsoft Entra.

  3. Aceda a Registos de Aplicações.

  4. Selecione uma aplicação existente ou crie uma nova.

  5. Depois de a aplicação estar pronta, localize o ID de cliente e o ID de inquilino nas propriedades da aplicação:

    Localizar o ID de cliente e o ID de inquilino a partir das propriedades da sua aplicação ID do Microsoft Entra.

  6. Anote o ID de cliente e o ID de inquilino. Estes valores são utilizados para criar o pedido de API.

Adicionar as identidades permitidas ou identidades à conta do Intelligent Recommendations

Antes de continuar, tem de adicionar a identidade à lista autenticada na sua conta do Intelligent Recommendations.

  1. Inicie sessão no portal do Azure.
  2. Navegue para Contas do Intelligent Recommendations.
  3. Selecione a conta que pretende consultar.
  4. No menu, selecione Autenticação de Ponto Final.
  5. Adicione o novo ID de principal da aplicação (o ID de principal é o mesmo que o ID de cliente, que foi encontrado anteriormente).
  6. Altere o tipo de principal para "Aplicação".

Nota

A atualização destas definições pode demorar até 15 minutos.

Passo 3: Configurar autenticação

O último passo é configurar o mecanismo de autenticação. Pode utilizar um segredo ou um certificado. Neste guia de iniciação rápida, vê como criar um segredo.

  1. No painel de navegação esquerdo, selecione Certificados e Segredos.
  2. Selecione Novo Segredo do Cliente. Este valor secreto é privado e tem de ser armazenado num local seguro, pois precisará dele no passo seguinte.

Nota

Só pode copiar o valor do segredo imediatamente após a criação, conforme mostrado: Copiar o segredo da aplicação.

Agora que preparou as informações necessárias, está pronto para criar um pedido de API e chamar o serviço Intelligent Recommendations.

Construir o pedido de API

A secção seguinte fornece duas formas de chamar a API Intelligent Recommendations com ferramentas da API REST. Para utilizar uma aplicação diferente para chamar o ponto final do Intelligent Recommendations, certifique-se de que está a utilizar uma ferramenta da API REST que suporte a autenticação OAuth2.

Neste guia de início rápido, explica como configurar um pedido de API para obter uma lista popular de itens com Insomnia e com código C#.

Antes de continuar, certifique-se de que cumpre com cada um dos seguintes pré-requisitos:

  1. ID do inquilino do ID do Microsoft Entra
  2. ID de cliente da aplicação do chamador
  3. Valor do segredo da aplicação
  4. A consulta HTTP que utiliza o URL do ponto final de entrega da conta do Intelligent Recommendations composta por caminho de consulta/parâmetros válidos, conforme descrito na API Intelligent Recommendations

Nota

No seguinte pedido de exemplo, estamos a utilizar o nome da conta irtest e o ponto final de serviço serving01.

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

Chamar o ponto final com o Explorador de resultados

IMPORTANTE A partir de abril de 2023, o Site do Portal IR e a ferramenta Explorador de Resultados foram preteridos e já não estão em utilização. Para ver resultados, utilize uma das opções nas seguintes secções:

Chamar o ponto final com o Insomnia

Pode utilizar o Insomnia ou uma ferramenta da API REST semelhante que suporte a autenticação OAuth2 para enviar pedidos de teste para um ponto final do Intelligent Recommendations.

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

Processo de autenticação

  1. Na secção Começar, selecione Criar um pedido.

  2. Navegue para o separador Autorização do compositor de pedidos e configure-o com os seguintes valores:

    • Defina o tipo como OAuth 2.0
    • Defina Adicionar Cabeçalhos de Autorização como Pedir Cabeçalhos
    • Criar um novo token com algum nome de token.
    • Tipo de Concessão = Credenciais de Cliente
    • URL do Token de Acesso = https://login.microsoftonline.com/<callerTenantID>/oauth2/v2.0/token
    • ID de Cliente = <yourAppClientID>
    • Segredo do Cliente = <yourAppSecretValue>
    • Âmbito = <URL DO SEU PONTO FINAL>/.predefinido
    • Mantenha a Autenticação de Cliente definida como Enviar como Cabeçalho de Autorização Básico

    Eis o aspeto antes da geração do token:

    Exemplo de um formulário de autorização concluído.

  3. Desloque-se para baixo até encontrar o botão Obter novo token de acesso. Se estiver configurado corretamente, a seleção do botão abre uma nova janela com um token viável.

  4. Selecione Utilizar Token.

    Exemplo de um token de acesso adequado.

Publicar o pedido

Agora que está autenticado, pode publicar o pedido real.

  1. Publique o pedido e, em seguida, selecione Enviar. Consulte o nosso Guia de Pedidos de Amostra para uma lista de pedidos de API adicionais pré-configurados que pode experimentar.

  2. A resposta JSON aparece no fundo do ecrã:

    Exemplo de resultados devolvidos ao efetuar um pedido de API popular.

Nota

Uma resposta bem sucedida devolverá uma lista de itens classificada na secção Itens da resposta JSON. Neste cenário, o ID do item mais popular é 712. Pode ver a lista completa de Códigos de Estado da API aqui.

Chamar o ponto final com código C#

Para fazer uma chamada bem sucedida para o ponto final do Intelligent Recommendations utilizando C#, prepare as seguintes informações:

  1. ID do inquilino do ID do Microsoft Entra
  2. ID de cliente da aplicação do chamador
  3. Valor do segredo da aplicação
  4. A consulta HTTP que utiliza o URL de ponto final de entrega da conta do Intelligent Recommendations composta por caminho de consulta/parâmetros válidos, conforme descrito na especificação da API Intelligent Recommendations

Em seguida, copie o código da amostra fornecido, 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 com êxito contém uma lista classificada de itens recomendados com base no cenário sob a secção Itens. Neste cenário, o ID do item mais popular é 712. Pode ver a lista completa de Códigos de Estado da API aqui.

Chamar o ponto final com Azure Machine Learning

Para fazer pedidos de API ao serviço Intelligent Recommendations utilizando o Azure Machine Learning, pode utilizar este Jupyter Notebook do Recomendador de Retalho. Como bónus adicional, o bloco de notas também inclui passos para combinar o Intelligent Recommendations com o Personalizador do Azure! Ver mais: Jupyter Notebook do Recomendador de Retalho.

Consulte também

Referência da API do Intelligent Recommendations
Códigos de Estado da API
Guia de início rápido: Configurar e executar o Intelligent Recommendations com dados de amostra
Descrição geral da implementação
Utilizar contratos de dados para partilhar dados