Del via


Startvejledning: Foretag et godkendt API-kald

Denne artikel hjælper dig med at oprette en godkendt anmodning til tjenesten Intelligent Recommendations og få vist resultater.

Oversigt

Hvis du vil foretage en vellykket API-anmodning, skal du forberede følgende oplysninger:

  • Microsoft Entra ID-lejer-id
  • Opkalderens programklient-id
  • Programmets hemmelighedsværdi
  • Den HTTP-forespørgsel, der bruger URL-adressen til leveringsslutpunktet for kontoen til Intelligent Recommendations, der er sammensat med en gyldig forespørgselssti/gyldige forespørgselsparametre som beskrevet i API'en til Intelligent Recommendations.

Hvis du vil have hjælp til at finde disse oplysninger, skal du fortsætte med at læse.

Hvis du har forberedt disse oplysninger, kan du gå videre til afsnittet Udarbejd API-anmodningen i denne startvejledning.

Forudsætninger

Før du starter, skal du sørge for at have:

Bemærk

Når tjenesten er blevet klargjort korrekt, kan det tage op til én dag, før AI-ML-modeloplæringen har behandlet inputdataene og genererede rangerede lister. Hvis du lige har klargjort din første konto til Intelligent Recommendations, kan det være en god ide at vente, før du fortsætter.

Trin 1: Opret URL-adressen til slutpunktet

Alle konti til Intelligent Recommendations kræver mindst ét serviceslutpunkt for at kunne levere anmodninger. Et serviceslutpunkt indeholder en entydig URL-adresse, der kan bruges til at kalde tjenesten.

For at oprette en korrekt API-anmodning skal du finde URL-adressen til serviceslutpunktet ved hjælp af din Azure-portalkonto:

  1. Log på Azure-portal.

  2. Gå til Konti til Intelligent Recommendations.

  3. Vælg den konto, du vil forespørge.

  4. Vælg Serviceslutpunkter i afsnittet Komponenter i menuen.

  5. Vælg det serviceslutpunkt, du vil bruge.

  6. Find URL-adressen i egenskaberne for slutpunktsressourcen som vist:

    Find URL-adressen til tjenesteslutpunktet i egenskaberne for slutpunktsressourcen.

URL-adressen er struktureret på følgende måde:

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

Trin 2: Konfigurer et klientprogram

Intelligent Recommendations kræver en OAuth2-godkendelse. Fastlæg (eller opret) det Microsoft Entra ID-program, hvorfra serviceslutpunktet skal kaldes med godkendelse. Alle ikke-godkendte kald mislykkes, og der vises en fejl.

  1. Log på Azure-portal.

  2. Gå til Microsoft Entra ID.

  3. Gå til Appregistreringer.

  4. Vælg et eksisterende program, eller opret et nyt.

  5. Når programmet er klar, skal du finde klient-id'et og lejer-id'et i programegenskaberne:

    Finde klient-id'et og lejer-id'et i programegenskaberne for dit Microsoft Entra ID-program.

  6. Notér klient-id'et og lejer-id'et ned. Disse værdier bruges til at oprette API-anmodningen.

Føj de(n) tilladte identitet(er) til kontoen til Intelligent Recommendations

Før du fortsætter, skal du føje identiteten til den godkendte liste på din konto til Intelligent Recommendations.

  1. Log på Azure-portal.
  2. Gå til Konti til Intelligent Recommendations.
  3. Vælg den konto, du vil forespørge.
  4. Vælg Slutpunktsgodkendelser i menuen.
  5. Tilføj det nye programprincipal-id (principal-id'et er det samme som det klient-id, du fandt tidligere).
  6. Skift principaltypen til "Program".

Bemærk

Det kan tage op til 15 minutter at opdatere disse indstillinger.

Trin 3: Konfigurer godkendelse

Det sidste trin er at konfigurere godkendelsesmekanismen. Du kan enten bruge en hemmelighed eller et certifikat. I denne startvejledning kan du se, hvordan du opretter en hemmelighed.

  1. Vælg Certifikater og hemmeligheder i venstre navigationsrude.
  2. Vælg Ny klienthemmelighed. Denne hemmelighedsværdi er privat og skal gemmes på et sikkert sted, da du skal bruge den i næste trin.

Bemærk

Du kan kun kopiere hemmelighedsværdien direkte efter oprettelsen som vist: Kopiér din programhemmelighed.

Nu, hvor du har forberedt de nødvendige oplysninger, er du klar til at oprette en API-anmodning og kalde tjenesten Intelligent Recommendations.

Konstruer API-anmodningen

I det næste afsnit findes to måder, hvorpå du kan kalde API'en med Intelligent Recommendations ved hjælp af REST API-værktøjer. For at bruge et andet program til at kalde slutpunktet til Intelligent Recommendations skal du sikre dig, at du bruger et REST API-værktøj, der understøtter OAuth2-godkendelse.

I denne startvejledning gennemgår du, hvordan du konfigurerer en API-anmodning for at hente en meget udbredt liste over elementer med Insomnia og C#-kode.

Før du fortsætter, skal du sørge for, at du har hver af følgende forudsætninger:

  1. Microsoft Entra ID-lejer-id
  2. Opkalderens programklient-id
  3. Programmets hemmelighedsværdi
  4. Den HTTP-forespørgsel, der bruger URL-adressen til leveringsslutpunktet for kontoen til Intelligent Recommendations, der er sammensat med en gyldig forespørgselssti/gyldige forespørgselsparametre som beskrevet i API'en til Intelligent Recommendations

Bemærk

I følgende eksempelanmodning bruger vi kontonavnet irtest og serviceslutpunktet serving01.

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

Kald slutpunktet med Resultatoversigt

VIGTIGT! Fra og med april 2023 udgår værktøjet IR Portal Website and Results Explorer og er ikke længere i brug. Hvis du vil have vist resultater, skal du bruge en af indstillingerne i følgende afsnit:

Kald slutpunktet med Insomnia

Du kan bruge Insomnia eller et lignende REST API-værktøj, der understøtter OAuth2-godkendelse, til at sende testanmodninger til et slutpunkt for Intelligent Recommendations.

Du kan finde flere oplysninger under Brug af Insomnia med Dataverse web-API'en

Godkendelsesproces

  1. Vælg Opret en anmodning i afsnittet Start her.

  2. Naviger til fanen Godkendelse for anmodningsoprettelsesfunktionen, og konfigurer den med følgende værdier:

    • Angiv typen til OAuth 2.0
    • Angiv Tilføj godkendelsesheadere til Anmodningsheadere
    • Opret et nyt token med et tokennavn.
    • Tilskudstype = Klientlegitimationsoplysninger
    • URL-adresse til adgangstoken = https://login.microsoftonline.com/<callerTenantID>/oauth2/v2.0/token
    • Klient-id = <ditProgramklient-id>
    • Klienthemmelighed = <ditProgramhemmelighedsværdi>
    • Omfang = <URL-ADRESSEN TIL DIT SLUTPUNKT>/.default
    • Sørg for, at klientgodkendelsen er angivet til Send som grundlæggende godkendelsesheader

    Sådan ser det ud, før der genereres tokens:

    Eksempel på en udfyldt autorisationsformular.

  3. Rul ned på siden, indtil du finder knappen Hent nyt adgangstoken. Hvis knappen er konfigureret korrekt, åbnes der et nyt vindue med et brugbart token, når du vælger knappen.

  4. Vælg Brug token.

    Eksempel på en korrekt adgangstoken.

Angiv anmodningen

Nu, hvor du er godkendt, kan du angive den faktiske anmodning.

  1. Angiv anmodningen, og vælg derefter Send. Se vores vejledning til eksempelanmodninger for at få en liste over yderligere forudkonfigurerede API-anmodninger, du kan afprøve.

  2. JSON-svaret vises nederst på skærmen:

    Eksempel på resultater, der returneres, når du foretager en populær API-anmodning.

Bemærk

Hvis svaret lykkes, returneres der en oversigt over varer i afsnittet Varer JSON-svaret. I dette scenarie er det mest populære vare-id 712. Du kan se hele listen over API-statuskoder her.

Kald slutpunktet med C#-kode

Hvis du vil foretage et vellykket opkald til slutpunktet for Intelligent Recommendations ved hjælp af C#, skal du forberede følgende oplysninger:

  1. Microsoft Entra ID-lejer-id
  2. Opkalderens programklient-id
  3. Programmets hemmelighedsværdi
  4. Den HTTP-forespørgsel, der bruger URL-adressen til leveringsslutpunktet for kontoen til Intelligent Recommendations, der er sammensat med en gyldig forespørgselssti/gyldige forespørgselsparametre som beskrevet i specifikationen af API'en til Intelligent Recommendations

Kopiér derefter den viste eksempelkode, opdater de relevante felter, og udfør handlingen.

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

Et vellykket svar indeholder en rangeret liste over anbefalede elementer baseret på scenariet under sektionen Elementer. I dette scenarie er det mest populære vare-id 712. Du kan se hele listen over API-statuskoder her.

Kalde slutpunktet med Azure Machine Learning

Hvis du vil foretage API-anmodninger til tjenesten Intelligent Recommendations ved hjælp af Azure Machine Learning, kan du bruge denne anbefaling til forhandler, Jupyter Notebook. Notesbogen indeholder også trin til at kombinere Intelligent Recommendations med Azure Personalizer! Se mere: Jupyter Notebook, anbefaling til forhandler.

Se også

Intelligent Recommendations-API
API-statuskoder
Startvejledning: Konfigurer og kør Intelligent Recommendations med prøvedata
Oversigt over udrulning
Brug datakontrakter til at dele data