Delen via

Aan de slag: een geverifieerde API-aanroep plaatsen

  • Artikel

Dit artikel helpt u om een geverifieerde aanvraag naar de Intelligent Recommendations-service op te stellen en resultaten te bekijken.

Samenzicht

Om een succesvolle API-aanvraag te plaatsen, moet u de volgende informatie voorbereiden:

  • Tenant-id van Microsoft Entra ID
  • Client-id van degene die de toepassing aanroept
  • De geheime waarde voor de toepassing
  • De HTTP-query met behulp van het Intelligent Recommendations-account dat de eindpunt-URL levert, samengesteld met geldige querypad/-parameters, zoals beschreven in de Intelligent Recommendations-API.

Lees verder voor hulp bij het vinden van deze informatie.

Als u deze informatie hebt voorbereid, kunt u naar de sectie De API-aanvraag opstellen van deze aan de slag gaan.

Vereisten

Zorg ervoor dat u voordat u begint de volgende zaken paraat hebt:

Notitie

Zodra de service is ingericht, kan het tot een dag duren voordat de AI-ML-modeltraining de invoergegevens heeft verwerkt en gerangschikte lijsten heeft gemaakt. Als u zojuist uw eerste Intelligent Recommendations-account heeft ingericht, kunt u het best even wachten voordat u verdergaat.

Stap 1: maak de eindpunt-URL

Voor elk Intelligent Recommendations-account is ten minste één service-eindpunt nodig om aanvragen te verwerken. Een service-eindpunt biedt een unieke URL voor het aanroepen van de service.

Zoek de service-eindpunt-URL met uw Azure-portalaccount om een correcte API-aanvraag op te stellen:

  1. Meld u aan bij de Azure-portal.

  2. Ga naar Intelligent Recommendations-accounts.

  3. Selecteer het account dat u wilt opvragen.

  4. Selecteer Service-eindpunten uit de sectie Onderdelen van het menu.

  5. Selecteer het service-eindpunt dat u wilt gebruiken.

  6. Zoek de URL in de eigenschappen van de eindpunt-resource, zoals weergegeven:

    Zoek de service-eindpunt-URL in de eigenschappen van de eindpunt-resource.

De URL is als volgt opgebouwd:

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

Stap 2: stel een clienttoepassing in

Voor Intelligent Recommendations is een OAuth2-authenticatie nodig. Bepaal (of maak) de Microsoft Entra ID-toepassing van waaruit u het service-eindpunt met authenticatie wilt aanroepen. Alle niet-geverifieerde aanroepen mislukken met een fout.

  1. Meld u aan bij de Azure-portal.

  2. Ga naar Microsoft Entra ID.

  3. Ga naar App-registraties.

  4. Selecteer een bestaande toepassing of maak een nieuwe.

  5. Zodra de toepassing gereed is, zoekt u de client-id en tenant-id in de toepassingseigenschappen:

    Zoek de client-id en de tenant-id in de toepassingseigenschappen van uw Microsoft Entra ID-toepassing.

  6. Noteer de client-id en tenant-id. Deze waarden worden gebruikt om de API-aanvraag te maken.

Voeg de toegestane identiteit of identiteiten toe aan het Intelligent Recommendations-account

Voordat u doorgaat, moet u de identiteit toevoegen aan de geverifieerde lijst in uw Intelligent Recommendations-account.

  1. Meld u aan bij de Azure-portal.
  2. Ga naar Intelligent Recommendations-accounts.
  3. Selecteer het account dat u wilt opvragen.
  4. Selecteer in het menu Eindpunt-authenticaties.
  5. Voeg de nieuwe principal-id van de toepassing toe (de principal-id is hetzelfde als de client-id, die u eerder hebt gevonden).
  6. Wijzig het principaltype in "Toepassing".

Notitie

Het bijwerken van deze instellingen kan tot 15 minuten duren.

Stap 3: authenticatie configureren

De laatste stap is het configureren van het authenticatiemechanisme. U kunt een geheim of een certificaat gebruiken. In deze Aan de slag maken we een geheim.

  1. Selecteer in het linkernavigatiedeelvenster de optie Certificaten en geheimen.
  2. Selecteer Nieuw clientgeheim. Deze geheime waarde is privé en moet op een veilige plaats worden bewaard, omdat u deze in de volgende stap nodig hebt.

Notitie

U kunt de geheime waarde alleen direct na het maken kopiëren, zoals weergegeven: Kopieer uw toepassingsgeheim.

Nu u de benodigde informatie hebt voorbereid, bent u klaar om een API-aanvraag te maken en de Intelligent Recommendations-service aan te roepen.

De API-aanvraag opstellen

In de volgende sectie geven we twee manieren waarop u de Intelligent Recommendations-API kunt aanroepen met REST API-tools. Als u een andere toepassing wilt gebruiken om het Intelligent Recommendations-eindpunt aan te roepen, moet u ervoor zorgen dat u een REST API-tool gebruikt die OAuth2-authenticatie ondersteunt.

In deze Aan de slag-gids doorloopt u de procedure die nodig is om een API-aanvraag te configureren voor het ophalen van een populaire lijst met items met zowel Insomnia- als C#-code.

Zorg er voordat u doorgaat voor dat u elk van de volgende zaken paraat hebt:

  1. Tenant-id van Microsoft Entra ID
  2. Client-id van degene die de toepassing aanroept
  3. De geheime waarde voor de toepassing
  4. De HTTP-query met behulp van het Intelligent Recommendations-account dat de eindpunt-URL levert, samengesteld met geldige querypad/-parameters, zoals beschreven in de Intelligent Recommendations-API

Notitie

In het volgende voorbeeldaanvraag gebruiken we de accountnaam irtest en het service-eindpunt serving01.

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

Het eindpunt aanroepen met Results Explorer

BELANGRIJK Vanaf april 2023 zijn de IR Portal-website en de tool Resultatenverkenner verouderd en niet meer in gebruik. Gebruik een van de opties in de volgende secties om resultaten te bekijken:

Het eindpunt aanroepen met Insomnia

U kunt Insomnia, of een vergelijkbare REST API-tool die OAuth2-authenticatie ondersteunt, gebruiken om testaanvragen naar een Intelligent Recommendations-eindpunt te sturen.

Zie Insomnia gebruiken met de Dataverse-web-API voor meer informatie

Authenticatieproces

  1. Selecteer onder de sectie Aan de slag op Een aanvraag maken.

  2. Navigeer naar het tabblad Autorisatie van de aanvraag-composer en configureer dit met de volgende waarden:

    • Stel het type in op OAuth 2.0
    • Stel Autorisatie-headers toevoegen in op Headers aanvragen
    • Maak een nieuw token met een willekeurige tokennaam.
    • Toekenningstype = Clientreferenties
    • Toegangstoken-URL = https://login.microsoftonline.com/<callerTenantID>/oauth2/v2.0/token
    • Client-id = <yourAppClientID>
    • Clientgeheim = <yourAppSecretValue>
    • Bereik = <UW EINDPUNT-URL>/.default
    • Houd Clientverificatie ingesteld op Verzenden als basisverificatiekoptekst

    Zo ziet het eruit vóór het genereren van een token:

    Voorbeeld van een ingevuld autorisatieformulier.

  3. Scrol omlaag op de pagina totdat u de knop Nieuw toegangstoken ophalen vindt. Indien correct geconfigureerd, zal het selecteren van de knop een nieuw venster openen met een bruikbaar token.

  4. Selecteer Token gebruiken.

    Voorbeeld van een goed toegangstoken.

De aanvraag plaatsen

Nu u bent geverifieerd, kunt u de daadwerkelijke aanvraag plaatsen.

  1. Plaats uw aanvraag en selecteer vervolgens Verzenden. Zie onze Handleiding voor voorbeeldaanvragen voor een lijst met aanvullende, vooraf geconfigureerde API-aanvragen die u kunt uitproberen.

  2. De JSON-respons verschijnt onder aan het scherm:

    Voorbeeld van resultaten die worden geretourneerd bij het plaatsen van een populaire API-aanvraag.

Notitie

Een succesvolle respons retourneert een gerangschikte lijst met items in de sectie Items van de JSON-respons. Voor dit scenario is de meest populaire item-ID 712. U kunt de volledige lijst met API-statuscodes hier bekijken.

Het eindpunt aanroepen met C#-code

Bereid de volgende informatie voor om een succesvolle aanroep te doen naar het Intelligent Recommendations-eindpunt met behulp van C#:

  1. Tenant-id van Microsoft Entra ID
  2. Client-id van degene die de toepassing aanroept
  3. De geheime waarde voor de toepassing
  4. De HTTP-query met behulp van het Intelligent Recommendations-account dat de eindpunt-URL levert, samengesteld met geldige querypad/-parameters, zoals beschreven in de Intelligent Recommendations-API-specificatie

Kopieer vervolgens de geleverde voorbeeldcode, werk de betreffende velden bij en voer het uit.

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

Een succesvolle respons bevat een gerangschikte lijst met aanbevolen items op basis van het scenario onder de sectie Items. Voor dit scenario is de meest populaire item-ID 712. U kunt de volledige lijst met API-statuscodes hier bekijken.

Het eindpunt aanroepen met Azure Machine Learning

Als u API-aanvragen wilt indienen bij de Intelligent Recommendations-service met behulp van Azure Machine Learning, kunt u dit Jupyter Notebook voor Retail Recommender gebruiken. Als extra bonus bevat de notebook ook stappen voor het combineren van Intelligent Recommendations met Azure Personalizer! Meer bekijken: Jupyter Notebook voor Retail Recommender.

Zie ook

API-referentie voor Intelligent Recommendations
API-statuscodes
Snelstartgids: Intelligent Recommendations instellen en uitvoeren met voorbeeldgegevens
Implementatieoverzicht
Gegevenscontracten gebruiken om gegevens te delen