Dela via

Snabbstartsguide: Ringa ett autentiserat API-samtal

  • Artikel

Denna artikel hjälper dig skapa en autentiserad förfrågan till tjänsten Intelligent Recommendations och hur du visar resultat.

Översikt

För att få en lyckad API-förfrågan måste du förbereda följande information:

  • Klientorganisations-ID för Microsoft Entra ID
  • Uppringarens appklient-ID
  • Appens hemlighetsvärde
  • HTTP-frågan med kontot Intelligent Recommendations som slutpunkt URL:en består av giltiga frågesökväg/parametrar enligt beskrivningen i API för Intelligent Recommendations.

Fortsätt läsa om du vill ha hjälp med att hitta den här informationen.

Om du har förberett den här informationen kan du hoppa till Avsnittet om API-begäran i den här snabbstartsguiden.

Förutsättningar

Innan du kan börja bör du kontrollera att du har:

Kommentar

När tjänsten väl har tillhandahållits kan det ta upp till en dag för AI-ML-modellutbildningen att bearbeta indata och producera rankade listor. Om du just har etablerat ditt första konto för Intelligent Recommendations kan det vara bra att vänta innan du går vidare.

Steg 1: Skapa en slutpunkt-URL

För varje konto för Intelligent Recommendations krävs minst en slutpunkt för att betjäna förfrågningar. En tjänstslutpunkt en unik URL för anrop till tjänsten.

Leta upp en korrekt API-begäran genom att leta upp slutpunkt URL:en med ditt Azure Portal-konto:

  1. Logga in på Azure Portal.

  2. Navigera till Skapa ett nytt konto för Intelligent Recommendations.

  3. Välj det konto du vill fråga.

  4. Från avsnittet Komponenter av denna meny, välj Tjänstslutpunkt.

  5. Välj den tjänstslutpunkt som du vill använda.

  6. Leta upp URL:en i egenskaperna för slutpunkt resurs enligt följande:

    Leta upp tjänstslutpunkt i egenskaperna för slutpunkt resurs.

URL:en är strukturerad enligt följande:

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

Steg 2: Konfigurera ett klientprogram

Intelligent Recommendations kräver en OAuth2-autentisering. Bestäm (eller skapa) Microsoft Entra ID-programmet från vilket tjänstens slutpunkt ska anropas med autentisering. Alla oauterade anrop misslyckas och ett fel uppstår.

  1. Logga in på Azure Portal.

  2. Gå till Microsoft Entra ID.

  3. Gå till Appregistreringar.

  4. Välj en befintlig app eller skapa en ny.

  5. Leta upp klient-ID och klient-ID i programegenskaperna när programmet är klart:

    Leta reda på klient-ID och klient-ID från programegenskaperna för ditt Microsoft Entra ID-program.

  6. Notera klient-ID:t och klient-ID:t. Dessa värden används för att skapa API-begäran.

Lägga till identiteter eller identiteter som är tillåtna i kontot för Intelligent Recommendations

Innan du går vidare måste du lägga till identiteten i den autentiserade listan i ditt konto för Intelligent Recommendations.

  1. Logga in på Azure Portal.
  2. Navigera till Skapa ett nytt konto för Intelligent Recommendations.
  3. Välj det konto du vill fråga.
  4. Från menyn väljer du slutpunktautentiseringar.
  5. Lägg till det nya programmets huvud-ID (det primära ID:t är samma som klient-ID:t, som du hittade tidigare).
  6. Ändra huvudtypen till Program.

Kommentar

Det kan ta upp till 15 minuter att uppdatera inställningarna.

Steg 3: Konfigurera autentisering

Det sista steget är att konfigurera autentiseringsmekanismen. Du kan använda antingen en hemlighet eller ett certifikat. I den här snabbstartsguiden skapar vi en hemlighet.

  1. I det vänstra navigeringsfönstret, välj certifikat och hemligheter.
  2. Välj Ny klienthemlighet. Det här säkerhetsvärdet är privat och måste lagras på en säker plats, eftersom det behövs i nästa steg.

Kommentar

Du kan bara kopiera det hemliga värdet direkt efter skapandet, enligt: Kopiera programmets hemlighet.

Nu när du har förberett informationen kan du skapa en API-begäran och anropa tjänsten Intelligent Recommendations.

Konstruera API-begäran

I nästa avsnitt ger vi två exempel på sätt att anropa API för Intelligent Recommendations med REST-API verktyg. Om du vill använda ett annat program för att anropa slutpunkten för Intelligent Recommendations att du använder ett REST-API som stöder OAuth2-autentisering.

I den här snabbstartsguiden går du igenom hur du konfigurerar en API-begäran för att hämta en populär lista med objekt både med Insomnia och med C#-kod.

Innan du går vidare bör du kontrollera att du har alla följande krav:

  1. Klientorganisations-ID för Microsoft Entra ID
  2. Uppringarens appklient-ID
  3. Appens hemlighetsvärde
  4. HTTP-frågan med kontot Intelligent Recommendations som slutpunkt URL:en består av giltiga frågesökväg/parametrar enligt beskrivningen i API för Intelligent Recommendations

Kommentar

I följande exempelbegäran använder vi kontonamnet irtest och slutpunkttjänst serving01.

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

Anropa slutpunkt med Resultatutforskare

VIKTIGT Från och med april 2023 har IR-portalens webbplats och verktyget Resultatutforskaren tagits bort och används inte längre. Om du vill visa resultat använder du något av alternativen i följande avsnitt:

Ringa slutpunkt med Insomnia

Du kan använda Insomnia eller ett liknande REST-API-verktyg som stöder OAuth2-autentisering för att skicka testförfrågningar till en slutpunkt för Intelligent Recommendations.

Mer information finns i Använda Insomnia med Dataverse-webb-API

Autentiseringsprocess

  1. Under avsnittet Kom igång, välj Skapa en förfrågan.

  2. Gå till fliken Autentisering för förfrågan och konfigurera den med följande värden:

    • Ange typ till OAuth 2.0
    • Ange Lägg till auktoriseringshuvuden i Begärandehuvuden
    • Skapa en ny token med ett tokennamn.
    • Beviljandetyp = Autentiseringsuppgifter för klient
    • Åtkomsttoken URL = https://login.microsoftonline.com/<callerTenantID>/oauth2/v2.0/token
    • Klient-ID = <yourAppClientID>
    • Klienthemlighet = <yourAppSecretValue>
    • Omfattning = <YOUR ENDPOINT URL>/.default
    • Behåll klientautentiseringsuppsättningen Skicka som grundläggande auktoriseringshuvud

    Så här ser det ut innan tokengenereringen börjar:

    Exempel på ett ifyllda auktoriseringsformulär.

  3. Bläddra nedåt på sidan tills du hittar knappen Skaffa åtkomsttoken. Om du väljer en korrekt konfiguration öppnas ett nytt fönster med en fungerande token.

  4. Välj Använd token.

    Exempel på en korrekt åtkomsttoken.

Publicera begäran

Nu när du har autentiserats kan du publicera den faktiska förfrågan.

  1. Publicera förfrågan och välj Sedan Skicka. Se Guide eExempel på förfrågningar för en lista över ytterligare, förkonfigurerade API-förfrågningar som du kan prova.

  2. JSON-svaret kommer att visas längst ned på skärmen:

    Exempel på resultat som returneras när en populär API-förfrågan görs.

Kommentar

Ett framgångsrikt svar returnerar en lista med objekt i avsnittet Objekt i JSON-svaret. I det här scenariot är det mest populära objektet ID är 712. Du kan visa den fullständiga listan med API-statuskoder här.

Ringa slutpunkt med C#-kod

Förbered följande information om du vill ringa slutpunkt Intelligent Recommendations via C#:

  1. Klientorganisations-ID för Microsoft Entra ID
  2. Uppringarens appklient-ID
  3. Appens hemlighetsvärde
  4. HTTP-frågan med kontot Intelligent Recommendations som slutpunkt URL:en består av giltiga frågesökväg/parametrar enligt beskrivningen i API för Intelligent Recommendations specifikation

Kopiera sedan den givna exempelkoden, uppdatera relevanta fält och kör.

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

Ett lyckat svar kommer att innehålla en rankad lista med rekommenderade objekt baserat på scenariot under avsnittet Objekt. I det här scenariot är det mest populära objektet ID är 712. Du kan visa den fullständiga listan med API-statuskoder här.

Ringa slutpunkt Azure Machine Learning

To För att göra API-förfrågningar till tjänsten Intelligent Recommendations med Azure Machine Learning, kan du använda denna Retail Recommender Jupyter Notebook. Som en extra bonus innehåller Notebook även steg för att kombinera Intelligent Recommendations med Azure Personalizer! Se mer: Jupyter Notebook för Retail Recommender.

Se även

API-referens för Intelligent Recommendations
API-statuskoder
Snabbstartguide: Konfigurera och kör Intelligent Recommendations med exempeldata
Distributionsöversikt
Använd datakontrakt för att dela data