Compartir vía

Guía de inicio rápido: Realice una llamada a la API autenticada

  • Artículo

Este artículo le ayuda a construir una solicitud autenticada al servicio Intelligent Recommendations y a ver los resultados.

Introducción

Para realizar una solicitud API exitosa, debe preparar la siguiente información:

  • Id. de inquilino de Microsoft Entra ID
  • Id. de cliente de la aplicación que realiza la llamada
  • Valor de secreto de aplicación
  • La consulta HTTP que usa la cuenta de Intelligent Recommendations que entrega la URL punto de conexión compuesta con una ruta de consulta/parámetros válidos, como se describe en la API de Intelligent Recommendations.

Para obtener ayuda para localizar esta información, continúe leyendo.

Si tiene esta información preparada, puede saltar a la sección Construir la solicitud de API de esta guía de inicio rápido.

Requisitos previos

Antes de empezar, asegúrese de que tiene:

Nota

Una vez que el servicio se ha aprovisionado correctamente, la capacitación del modelo AI-ML puede tardar hasta un día en procesar los datos de entrada y producir listas clasificadas. Si acaba de aprovisionar su primera cuenta de Intelligent Recommendations, es posible que desee esperar antes de continuar.

Paso 1: Crear la URL de punto de conexión

Cada cuenta de Intelligent Recommendations requiere al menos un servicio punto de conexión para atender las solicitudes. Un servicio punto de conexión proporciona una URL única para llamar al servicio.

Para crear una solicitud de API adecuada, busque la URL del servicio punto de conexión con su cuenta de Azure Portal:

  1. Inicie sesión en Azure Portal.

  2. Navegue a Cuenta de Intelligent Recommendations.

  3. Seleccione la cuenta que desea consultar.

  4. En la sección Componentes del menú, seleccione Puntos de conexión de servicio.

  5. Seleccione el punto de conexión de servicio que desea usar.

  6. Ubique la URL en las propiedades del recurso punto de conexión, como se muestra:

    Ubique la URL del punto de conexión de servicio bajo las propiedades del recurso punto de conexión.

La URL tiene la siguiente estructura:

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

Paso 2: Configurar una aplicación cliente

Intelligent Recommendations requiere la autenticación OAuth2. Determine (o cree) la aplicación de Microsoft Entra ID desde la que llamar al servicio punto de conexión con autenticación. Cualquier llamada no autenticada fallará con un error.

  1. Inicie sesión en Azure Portal.

  2. Vaya a Microsoft Entra ID.

  3. Vaya a Registros de aplicaciones.

  4. Seleccione una aplicación existente o cree una nueva.

  5. Una vez que la aplicación esté lista, ubique la identificación del cliente y la identificación del inquilino en las propiedades de la aplicación:

    Busque el id. del cliente y el id. del inquilino en las propiedades de la aplicación de la aplicación Microsoft Entra ID.

  6. Tome nota de la identificación del cliente y la identificación del inquilino. Estos valores se utilizarán para crear la solicitud de API.

Agregar la identidad o identidades permitidas a la cuenta de Intelligent Recommendations

Antes de continuar, debe agregar la identidad a la lista autenticada en su cuenta de Intelligent Recommendations.

  1. Inicie sesión en Azure Portal.
  2. Navegue a Cuenta de Intelligent Recommendations.
  3. Seleccione la cuenta que desea consultar.
  4. En el menú, seleccione Autenticaciones de punto de conexión.
  5. Agregue el nuevo Id. principal de la aplicación (el Id. principal es el mismo que el Id. del cliente, que encontró anteriormente).
  6. Cambie el tipo principal a "Aplicación".

Nota

La actualización de esta configuración puede tardar hasta 15 minutos.

Paso 3: Configurar la autenticación

El último paso es configurar el mecanismo de autenticación. Puede utilizar un secreto o un certificado. En esta guía de inicio rápido, crearemos un secreto.

  1. En el panel de navegación izquierdo, seleccione Certificados y secretos.
  2. Seleccione Nuevo secreto de cliente. Este valor secreto es privado y debe almacenarse en un lugar seguro, ya que lo necesitará en el siguiente paso.

Nota

Solo puede copiar el valor secreto directamente después de la creación, como se muestra: Copiar el secreto de la aplicación.

Ahora que ha preparado la información necesaria, está listo para crear una solicitud de API y llamar al servicio de Intelligent Recommendations.

Construir la solicitud de API

En la siguiente sección se proporcionan dos formas de llamar a la API de Intelligent Recommendations con las herramientas API de REST. Para usar una aplicación diferente para llamar a las Intelligent Recommendations punto de conexión, asegúrese de estar usando una herramienta API de REST que admita la autenticación OAuth2.

En esta guía de inicio rápido, verá cómo configurar una solicitud de API para recuperar una lista popular de elementos tanto con Insomnia como con código C#.

Antes de continuar, asegúrese de que tiene cada uno de los siguientes requisitos previos:

  1. Id. de inquilino de Microsoft Entra ID
  2. Id. de cliente de la aplicación que realiza la llamada
  3. Valor de secreto de aplicación
  4. La consulta HTTP que usa la cuenta de Intelligent Recommendations que entrega la URL punto de conexión compuesta con una ruta de consulta/parámetros válidos, como se describe en la API de Intelligent Recommendations.

Nota

En la siguiente solicitud de ejemplo, usamos el nombre de la cuenta irtest y el servicio punto de conexión serving01.

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

Llame al punto de conexión con el Explorador de resultados

IMPORTANTE A partir de abril de 2023, el sitio web del portal de IR y la herramienta Explorador de resultados han quedado obsoletos y ya no están en uso. Para ver los resultados, utilice una de las opciones en las siguientes secciones:

Llamada al punto de conexión con Insomnia

Puede usar Insomnia o una herramienta API de REST similar que admita la autenticación OAuth2 para enviar solicitudes de prueba a un extremo de Intelligent Recommendations.

Para obtener más detalles, consulte Usar Insomnia con la API web de Dataverse

Proceso de autenticación

  1. En la sección Comenzar, haga clic en Crear una solicitud.

  2. Navegue a la pestaña Autorización del compositor de solicitudes y configurarlo con los siguientes valores:

    • Establecer el tipo en OAuth 2.0
    • Establezca Agregar encabezados de autorización en Encabezados de solicitud
    • Cree un nuevo token con algún nombre de token.
    • Tipo de concesión = Credenciales del cliente
    • URL de token de acceso = https://login.microsoftonline.com/<callerTenantID>/oauth2/v2.0/token
    • Client ID = <yourAppClientID>
    • Secreto de cliente = <yourAppSecretValue>
    • Ámbito = <YOUR ENDPOINT URL>/.default
    • Mantenga la Autenticación del cliente establecida en Enviar como encabezado de autenticación básico

    Así es como se ve antes de la generación del token:

    Ejemplo de un formulario de autorización completado.

  3. Desplácese hacia abajo en la página hasta que encuentre el botón Obtener nuevo token de acceso. Si está configurado correctamente, al seleccionar el botón se abrirá una nueva ventana con un token viable.

  4. Seleccione Usar token.

    Ejemplo de un token de acceso adecuado.

Publicar la solicitud

Ahora que está autenticado, puede publicar la solicitud real.

  1. Publique su solicitud y luego seleccione Enviar. Consulte nuestra Guía de solicitudes de muestrapara obtener una lista de solicitudes de API preconfiguradas adicionales que puede probar.

  2. La respuesta JSON aparecerá en la parte inferior de la pantalla:

    Ejemplo de resultados que se devuelven al realizar una solicitud de API popular.

Nota

Una respuesta exitosa devolverá una lista clasificada de elementos en la sección Elementos de la respuesta JSON. Para este escenario, el ID de artículo más popular es 712. Puede ver la lista completa de códigos de estado de API aquí.

Llamando al punto de conexión con código C#

Para realizar una llamada exitosa a las Intelligent Recommendations punto de conexión usando C#, prepare la siguiente información:

  1. Id. de inquilino de Microsoft Entra ID
  2. Id. de cliente de la aplicación que realiza la llamada
  3. Valor de secreto de aplicación
  4. La consulta HTTP que usa la cuenta de Recomendaciones inteligentes que entrega la URL punto de conexión compuesta con una ruta de consulta/parámetros válidos, como se describe en la especificación de la API de Intelligent Recommendations.

A continuación, copie el código de muestra dado, actualice los campos relevantes y ejecútelo.

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); }
}

Una respuesta exitosa contendrá una lista clasificada de elementos recomendados según el escenario bajo la sección Elementos. Para este escenario, el ID de artículo más popular es 712. Puede ver la lista completa de códigos de estado de API aquí.

Llamando al punto de conexión con Azure Machine Learning

Para realizar solicitudes de API al servicio de Intelligent Recommendations mediante Azure Machine Learning, puede usar Jupyter Notebook de recomendaciones para minoristas. Como beneficio adicional, el cuaderno también incluye pasos para combinar Recomendaciones inteligentes con Azure Personalizer. Más información: El Jupyter Notebook de recomendación minorista

Consulte también

Referencia de la API de Intelligent Recommendations
Códigos de estado de API
Guía de inicio rápido: configurar Intelligent Recommendations con daatos de ejemplo
Descripción general de la implementación
Usar contratos de datos para compartir datos