Guide de démarrage rapide : effectuer un appel d’API authentifié

  • Article

Cet article vous apprend à créer une demande authentifiée au service de recommandations intelligentes et à voir les résultats.

Résumé

Pour réussir une demande d’API, vous devez préparer les informations suivantes :

  • ID du locataire Microsoft Entra ID
  • ID client de l’application de l’appelant
  • Valeur du secret de l’application
  • La requête HTTP utilisant le compte Recommandations intelligentes d’URL point de terminaison de service composée d’un chemin/des paramètres de requête valides, comme indiqué dans l’API Recommandations intelligentes.

Pour obtenir de l’aide pour localiser ces informations, continuez à lire.

Si vous avez préparé ces informations, vous pouvez passer directement à la section Construire la requête API de ce guide de démarrage rapide.

Conditions préalables

Avant de commencer, assurez-vous d’avoir :

Note

Une fois le service configuré avec succès, la formation du modèle AI-ML peut prendre jusqu’à une journée pour traiter les données d’entrée et produire des listes classées. Si vous venez d’approvisionner votre premier compte Recommandations intelligentes, vous voudrez peut-être attendre avant de continuer.

Étape 1 : créer l’URL du point de terminaison

Chaque compte Recommandations intelligentes nécessite au moins un point de terminaison de service pour traiter les demandes. Un point de terminaison de service fournit une URL unique pour appeler le service.

Pour créer une demande d’API appropriée, localisez l’URL du point de terminaison de service à l’aide de votre compte de portail Azure :

  1. Connectez-vous au portail Azure.

  2. Accédez à Comptes Recommandations intelligentes.

  3. Sélectionnez le compte à interroger.

  4. Dans la section Composants du menu, sélectionnez Points de terminaison de service.

  5. Sélectionnez le point de terminaison de service à utiliser.

  6. Recherchez l’URL dans les propriétés de la ressource point de terminaison, comme indiqué :

    Recherchez l’URL du point de terminaison de service sous les propriétés de la ressource point de terminaison.

L’URL est structurée comme suit :

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

Étape 2 : Configurer une application cliente

Les recommandations intelligentes nécessitent l’authentification OAuth2. Déterminez (ou créez) l’application Microsoft Entra ID à partir de laquelle appeler le point de terminaison de service avec authentification. Tout appel non authentifié échoue avec une erreur.

  1. Connectez-vous au portail Azure.

  2. Accédez à Microsoft Entra ID.

  3. Accédez à Inscriptions d’applications.

  4. Sélectionnez une application existante ou créez-en une.

  5. Une fois l’application prête, localisez l’ID client et l’ID locataire dans les propriétés de l’application :

    Localisez l’ID client et l’ID locataire dans les propriétés de l’application de votre application Microsoft Entra ID.

  6. Notez l’ID client et l’ID locataire. Ces valeurs sont utilisées pour créer la requête API.

Ajouter la ou les identités autorisées au compte Recommandations intelligentes

Avant de continuer, vous devez ajouter l’identité à la liste authentifiée dans votre compte Recommandations intelligentes.

  1. Connectez-vous au portail Azure.
  2. Accédez à Comptes Recommandations intelligentes.
  3. Sélectionnez le compte à interroger.
  4. Dans le menu sélectionnez Authentifications de points de terminaison.
  5. Ajoutez le nouvel ID principal de l’application (l’ID principal est le même que l’ID client que vous avez trouvé précédemment).
  6. Changez le type de principal en "Application".

Note

La mise à jour de ces paramètres peut prendre jusqu’à 15 minutes.

Étape 3 : Configurer l’authentification

La dernière étape consiste à configurer le mécanisme d’authentification. Vous pouvez utiliser un secret ou un certificat. Dans ce guide de démarrage rapide, vous voyez comment créer un secret.

  1. Dans le volet de navigation de gauche, sélectionnez Certificats et secrets.
  2. Sélectionnez Nouvelle clé secrète client. Cette valeur de secret est privée et doit être stockée dans un endroit sécurisé, car vous en aurez besoin à l’étape suivante.

Note

Vous pouvez uniquement copier la valeur de la clé secrète juste après la création comme indiqué : Copiez le secret d’application.

Maintenant que vous avez préparé les informations nécessaires, vous êtes prêt à créer une demande d’API et à appeler le service Recommandations intelligentes.

Construire la requête API

La section suivante fournit deux exemples de façons d’appeler l’API Recommandations intelligentes avec les outils API REST. Pour utiliser une autre application pour appeler le point de terminaison des recommandations intelligentes, assurez-vous que vous utilisez un outil API REST qui prend en charge l’authentification OAuth2.

Dans ce guide de démarrage rapide, vous découvrirez comment configurer une demande d’API pour récupérer une liste populaire d’éléments à la fois avec Insomnia et avec le code C#.

Avant de continuer, assurez-vous que vous disposez de chacun des prérequis suivants :

  1. ID du locataire Microsoft Entra ID
  2. ID client de l’application de l’appelant
  3. Valeur du secret de l’application
  4. La requête HTTP utilisant le compte Recommandations intelligentes d’URL point de terminaison de service composée d’un chemin/des paramètres de requête valides, comme indiqué dans l’API Recommandations intelligentes

Note

Dans l’exemple de demande suivant, nous utilisons le nom du compte irtest et le service point de terminaison serving01.

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

Appelez le point de terminaison avec l’explorateur de résultats

IMPORTANT Depuis avril 2023, le site web IR Portal et l’outil Results Explorer sont obsolètes et ne sont plus utilisés. Pour voir les résultats, utilisez l’une des options dans les sections suivantes :

Appel du point de terminaison avec Insomnia

Vous pouvez utiliser Insomnia ou un outil API REST similaire qui prend en charge l’authentification OAuth2 pour envoyer des demandes de test à un point de terminaison Recommandations intelligentes.

Pour plus de détails, consultez Utiliser Insomnia avec l’API web Dataverse

Processus d’authentification

  1. Sous la section Commencer, sélectionnez Créer une demande.

  2. Naviguez vers l’onglet Autorisation du composeur de requêtes et configurez-le avec les valeurs suivantes :

    • Définir le type sur OAuth 2.0
    • Définissez Ajouter des en-têtes d’autorisation sur En-têtes de demande
    • Créez un jeton avec un nom de jeton.
    • Type d’autorisation = Informations d’identification du client
    • URL du jeton d’accès = https://login.microsoftonline.com/<callerTenantID>/oauth2/v2.0/token
    • ID client = <yourAppClientID>
    • Clé secrète client = <yourAppSecretValue>
    • Portée = <VOTRE URL DE POINT DE TERMINAISON>/.default
    • Gardez l’authentification client définie sur Envoyer comme en-tête d’authentification de base

    Voici à quoi cela ressemble avant la génération du jeton :

    Exemple de formulaire d’autorisation rempli.

  3. Faites défiler la page jusqu’à ce que vous trouviez le bouton Obtenez le nouveau token. S’il est configuré correctement, le bouton ouvre une nouvelle fenêtre avec un jeton viable lorsque vous le sélectionnez.

  4. Sélectionnez Utiliser un jeton.

    Exemple d’un token d’accès approprié.

Publier la demande

Maintenant que vous êtes authentifié, vous pouvez publier la demande réelle.

  1. Publiez votre demande, puis sélectionnez Envoyer. Consultez notre Guide des exemples de demandes pour obtenir une liste de demandes d’API préconfigurées supplémentaires que vous pouvez essayer.

  2. La réponse JSON apparaît en bas de l’écran :

    Exemple de résultats renvoyés lors d’une requête API populaire.

Note

Une réponse réussie renverra une liste classée des articles dans la section Articles de la réponse JSON. Pour ce scénario, l’ID d’article le plus populaire est 712. Vous pouvez consulter la liste complète des codes de statuts API.

Appel du point de terminaison avec le code C#

Pour réussir un appel au point de terminaison recommandations intelligentes à l’aide de C#, préparez les informations suivantes :

  1. ID du locataire Microsoft Entra ID
  2. ID client de l’application de l’appelant
  3. Valeur du secret de l’application
  4. La requête HTTP utilisant le compte Recommandations intelligentes d’URL point de terminaison de service composée d’un chemin/des paramètres de requête valides, comme indiqué dans la spécification de l’API Recommandations intelligentes

Ensuite, copiez l’exemple de code donné, mettez à jour les champs pertinents et exécutez.

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

Une réponse réussie contient une liste classée des articles recommandés en fonction du scénario sous la section Articles. Pour ce scénario, l’ID d’article le plus populaire est 712. Vous pouvez consulter la liste complète des codes de statuts API.

Appel du point de terminaison avec Azure Machine Learning

Pour envoyer des demandes d’API au service Recommandations intelligentes à l’aide d’Azure Machine Learning, vous pouvez utiliser Jupyter Notebook Retail Recommender. En prime, le bloc-notes comprend également des étapes pour combiner les recommandations intelligentes avec Azure Personalizer ! Pour en savoir plus : Jupyter Notebook Retail Recommender.

Voir aussi

Référence de l’API Recommandations intelligentes
Codes de statut API
Guide de démarrage rapide : configurer et exécuter des recommandations intelligentes avec des exemples de données
Présentation du déploiement
Utiliser des contrats de données pour partager des données