Freigeben über

Schnellstart-Anleitung: Einen authentifizierten API-Aufruf tätigen

  • Artikel

Dieser Artikel hilft Ihnen, eine authentifizierte Anfrage an den Dienst Intelligent Recommendations zu erstellen und die Ergebnisse zu sehen.

Überblick

Um eine erfolgreiche API-Anfrage zu stellen, müssen Sie die folgenden Informationen vorbereiten:

  • Microsoft Entra ID-Mandanten-ID
  • Client ID der Anwendung des Anrufers
  • Geheimer Wert der Bewerbung
  • Die HTTP-Abfrage unter Verwendung der URL des Endpunkts für das Konto für Intelligent Recommendations, der mit gültigen Abfragepfaden und -parametern versehen ist, wie in der API für Intelligent Recommendations beschrieben.

Wenn Sie Hilfe beim Auffinden dieser Informationen benötigen, lesen Sie weiter.

Wenn Sie diese Informationen vorbereitet haben, können Sie zum Abschnitt Konstruieren Sie die API-Anfrage dieser Schnellstartanleitung springen.

Anforderungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie über:

Notiz

Nach der erfolgreichen Bereitstellung des Dienstes kann es bis zu einem Tag dauern, bis das Training des KI-ML-Modells die Eingabedaten verarbeitet und Ranglisten erstellt hat. Wenn Sie gerade Ihr erstes Konto für Intelligent Recommendations eingerichtet haben, sollten Sie vielleicht noch warten, bevor Sie fortfahren.

Schritt 1: Erstellen Sie die Endpunkt-URL

Jedes Konto für Intelligent Recommendations benötigt mindestens einen Service-Endpunkt, um Anfragen zu bedienen. Ein Service-Endpunkt bietet eine eindeutige URL für den Aufruf des Dienstes.

Um eine korrekte API-Anfrage zu erstellen, suchen Sie die URL des Service-Endpunkts über Ihr Azure-Portal-Konto:

  1. Melden Sie sich beim Azure-Portal an.

  2. Navigieren Sie zu Intelligent Recommendations Konten.

  3. Wählen Sie das Konto, das Sie abfragen möchten.

  4. Wählen Sie im Menü unter Komponenten die Option Service-Endpunkte.

  5. Wählen Sie den Service-Endpunkt, den Sie verwenden möchten.

  6. Suchen Sie die URL in den Eigenschaften der Endpunktressource, wie gezeigt:

    Lokalisieren Sie die Service-Endpunkt-URL unter den Eigenschaften der Endpunkt-Ressource.

Die URL ist wie folgt aufgebaut:

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

Schritt 2: Legen Sie eine Client-Anwendung fest

Intelligent Recommendations erfordern eine OAuth2-Authentifizierung. Bestimmen (oder erstellen) Sie die Microsoft Entra ID-Anwendung, von der aus der Service-Endpunkt mit Authentifizierung aufgerufen werden soll. Alle nicht authentifizierten Aufrufe werden mit einem Fehler zurückgewiesen.

  1. Melden Sie sich beim Azure-Portal an.

  2. Wechseln Sie zu Microsoft Entra ID.

  3. Gehen Sie zu App-Registrierungen.

  4. Wählen Sie eine vorhandene Anwendung oder erstellen Sie eine neue.

  5. Sobald die Anwendung bereit ist, suchen Sie in den Anwendungseigenschaften die Client-ID und die Mieter-ID:

    Suchen Sie die Client-ID und die Mandant-ID in den Anwendungseigenschaften Ihrer Microsoft Entra ID-Anwendung.

  6. Notieren Sie sich die Client-ID und die ID des Mandanten. Diese Werte werden verwendet, um die API-Anfrage zu erstellen.

Fügen Sie die zugelassene(n) Identität(en) zum Konto Intelligent Recommendations hinzu

Bevor Sie fortfahren, müssen Sie die Identität zur authentifizierten Liste in Ihrem Konto für Intelligent Recommendations hinzufügen.

  1. Melden Sie sich beim Azure-Portal an.
  2. Navigieren Sie zu Intelligent Recommendations Konten.
  3. Wählen Sie das Konto, das Sie abfragen möchten.
  4. Wählen Sie aus dem Menü Endpunkt-Authentifizierungen.
  5. Fügen Sie die neue Prinzipal-ID der Anwendung hinzu (die Prinzipal-ID ist die gleiche wie die Client-ID, die Sie zuvor gefunden haben).
  6. Ändern Sie den Typ des Prinzipals in „Anwendung“.

Notiz

Das Aktualisieren dieser Einstellungen kann bis zu 15 Minuten dauern.

Schritt 3: Konfigurieren Sie die Authentifizierung

Der letzte Schritt besteht darin, den Authentifizierungsmechanismus zu konfigurieren. Sie können entweder ein Geheimnis oder ein Zertifikat verwenden. In diese Schnellstart-Anleitung erfahren Sie, wie Sie ein Geheimnis erstellen.

  1. Wählen Sie im linken Navigationsbereich Zertifikate & Geheimnisse.
  2. Wählen Sie Neues Client Geheimnis. Dieser geheime Wert ist privat und muss an einem sicheren Ort gespeichert werden, da Sie ihn im nächsten Schritt benötigen.

Notiz

Sie können den geheimen Wert nur direkt nach der Erstellung kopieren, wie gezeigt: Kopieren Sie Ihr Anwendungsgeheimnis.

Jetzt, da Sie die notwendigen Informationen vorbereitet haben, können Sie eine API-Anfrage erstellen und den Dienst Intelligent Recommendations aufrufen.

Konstruieren Sie die API-Anfrage

Im nächsten Abschnitt finden Sie zwei Möglichkeiten, die Intelligent Recommendations API mit REST-API-Tools aufzurufen. Wenn Sie den Endpunkt Intelligent Recommendations mit einer anderen Anwendung aufrufen möchten, stellen Sie sicher, dass Sie ein REST-API Tool verwenden, das die OAuth2-Authentifizierung unterstützt.

In dieser Anleitung zeigen wir Ihnen, wie Sie eine API-Anfrage konfigurieren, um eine beliebte Artikelliste sowohl mit Insomnia als auch mit C#-Code abzurufen.

Bevor Sie fortfahren, vergewissern Sie sich, dass Sie über alle folgenden Voraussetzungen verfügen:

  1. Microsoft Entra ID-Mandanten-ID
  2. Client ID der Anwendung des Anrufers
  3. Antrag geheimer Wert
  4. Die HTTP-Abfrage unter Verwendung der Endpunkt-URL des Kontos für Intelligent Recommendations mit gültigem Abfragepfad/Parametern, wie in der API für Intelligent Recommendations beschrieben

Notiz

In der folgenden Beispielanforderung verwenden wir den Kontonamen irtest und den Service-Endpunkt serving01.

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

Rufen Sie den Endpunkt mit Results explorer auf

WICHTIG Seit April 2023 sind die IR-Portal-Website und das Results Explorer-Tool veraltet und werden nicht mehr verwendet. Um Ergebnisse anzuzeigen, verwenden Sie eine der Optionen in den folgenden Abschnitten:

Aufrufen des Endpunkts mit Insomnia

Sie können Insomnia oder ein ähnliches REST-API Tool verwenden, das die OAuth2-Authentifizierung unterstützt, um Testanfragen an einen Endpunkt der Intelligent Recommendations zu senden.

Weitere Einzelheiten finden Sie unter Verwenden von Insomnia mit der Dataverse Web-API

Authentifizierungsprozess

  1. Wählen Sie unter dem Abschnitt Jetzt einsteigen Anfrage erstellen.

  2. Navigieren Sie zur Registerkarte Autorisierung des Request Composers und konfigurieren Sie sie mit den folgenden Werten:

    • Typ festlegen auf OAuth 2.0
    • Legen Sie Autorisierungskopfzeilen hinzufügen auf Anfragekopfzeilen fest
    • Erstellen Sie einen neuen Token mit einem Token-Namen.
    • Typ = Anmeldeinformationen des Clients
    • Zugriffs-Token URL = https://login.microsoftonline.com/<callerTenantID>/oauth2/v2.0/token
    • Client ID = <yourAppClientID>
    • Client Secret = <yourAppSecretValue>
    • Bereich = <YOUR ENDPOINT URL>/.default
    • Behalten Sie die Client-Authentifizierung auf Als Basic-Auth-Header senden festgelegt

    So sieht es vor der Token-Generierung aus:

    Beispiel für ein ausgefülltes Formular zur Autorisierung.

  3. Blättern Sie auf der Seite nach unten, bis Sie die Schaltfläche Neuen Zugriffstoken erhalten finden. Wenn Sie die Schaltfläche richtig konfiguriert haben, öffnet sich bei Auswahl der Schaltfläche ein neues Fenster mit einem funktionsfähigen Token.

  4. Wählen Sie Token verwenden.

    Beispiel für einen ordnungsgemäßen Access-Token.

Stellen Sie die Anfrage

Jetzt, da Sie authentifiziert sind, können Sie die eigentliche Anfrage stellen.

  1. Stellen Sie Ihre Anfrage ein und wählen Sie dann Senden. Eine Liste zusätzlicher, vorkonfigurierter API-Anfragen, die Sie ausprobieren können, finden Sie in unserem Beispielanfrage-Leitfaden.

  2. Die JSON-Antwort wird unten auf dem Bildschirm angezeigt:

    Beispiel für Ergebnisse, die bei einer beliebten API-Anfrage zurückgegeben werden.

Anmerkung

Bei einer erfolgreichen Antwort wird eine Rangliste der Elemente im Abschnitt Elemente der JSON-Antwort zurückgegeben. In diesem Szenario ist die beliebteste Element-ID 712. Hier finden Sie die vollständige Liste der API-Statuscodes.

Aufrufen des Endpunkts mit C#-Code

Um einen erfolgreichen Aufruf des Endpunkts Intelligent Recommendations mit C# durchzuführen, bereiten Sie die folgenden Informationen vor:

  1. Microsoft Entra ID-Mandanten-ID
  2. Client ID der Anwendung des Anrufers
  3. Antrag geheimer Wert
  4. Die HTTP-Abfrage unter Verwendung der URL des Endpunkts für das Konto für Intelligent Recommendations, der mit einem gültigen Abfragepfad bzw. gültigen Abfrageparametern gemäß der Spezifikation der API für Intelligent Recommendations erstellt wurde

Kopieren Sie als Nächstes den angegebenen Beispielcode, aktualisieren Sie die entsprechenden Felder und führen Sie ihn aus.

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

Eine erfolgreiche Antwort enthält eine Rangliste der empfohlenen Elemente auf der Grundlage des Szenarios unter dem Abschnitt Elemente. In diesem Szenario ist die beliebteste Element-ID 712. Hier finden Sie die vollständige Liste der API-Statuscodes.

Aufrufen des Endpunkts mit Azure Machine Learning

Um API-Anfragen an den Dienst Intelligent Recommendations mithilfe von Azure Machine Learning zu stellen, können Sie dieses Retail Recommender Jupyter Notebook verwenden. Als zusätzlichen Bonus enthält das Notebook auch Schritte zum Kombinieren von Intelligent Recommendations mit Azure Personalizer! Weitere Informationen: Jupyter Notebook „Retail Recommender“.

Siehe auch

Referenz der API für Intelligent Recommendations
API-Statuscode
Schnellstarthandbuch: Intelligent Recommendations mit Beispieldaten festlegen und ausführe
Übersicht über die Bereitstellung
Datenverträge zur gemeinsamen Nutzung von Daten verwenden