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:
En klargjort konto til Intelligent Recommendations. Hvis du endnu ikke har oprettet en konto til Intelligent Recommendations, skal du gå til Opret en ny konto til Intelligent Recommendations. Du kan også følge instruktionerne i Startvejledning: Konfigurer og kør Intelligent Recommendations med prøvedata.
Et program (Microsoft Entra ID-identitet) til at kalde tjenesten Intelligente anbefalinger.
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:
Log på Azure-portal.
Vælg den konto, du vil forespørge.
Vælg Serviceslutpunkter i afsnittet Komponenter i menuen.
Vælg det serviceslutpunkt, du vil bruge.
Find URL-adressen i egenskaberne for slutpunktsressourcen som vist:
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.
Log på Azure-portal.
Gå til Microsoft Entra ID.
Gå til Appregistreringer.
Vælg et eksisterende program, eller opret et nyt.
Når programmet er klar, skal du finde klient-id'et og lejer-id'et i programegenskaberne:
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.
- Log på Azure-portal.
- Gå til Konti til Intelligent Recommendations.
- Vælg den konto, du vil forespørge.
- Vælg Slutpunktsgodkendelser i menuen.
- Tilføj det nye programprincipal-id (principal-id'et er det samme som det klient-id, du fandt tidligere).
- 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.
- Vælg Certifikater og hemmeligheder i venstre navigationsrude.
- 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:
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:
- 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
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
Vælg Opret en anmodning i afsnittet Start her.
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:
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.
Vælg Brug token.
Angiv anmodningen
Nu, hvor du er godkendt, kan du angive den faktiske anmodning.
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.
JSON-svaret vises nederst på skærmen:
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:
- 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 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