Skrócony przewodnik: Wykonaj uwierzytelnione wywołanie interfejsu API
Ten artykuł pomaga w konstruowaniu uwierzytelnionego żądania do usługi Intelligent Recommendations i wyświetlaniu wyników.
Omówienie
Aby zażądać pomyślnego żądania interfejsu API, należy przygotować następujące informacje:
- Identyfikator dzierżawy w tożsamości Microsoft Entra
- Identyfikator klienta aplikacji wywołującego
- Tajna wartość aplikacji
- Zapytanie HTTP korzystające z adresu URL punktu końcowego obsługującego konto Intelligent Recommendations złożone z prawidłowej ścieżki/parametrów zapytania, zgodnie z opisem w interfejsie API Intelligent Recommendations.
Aby uzyskać pomoc w zlokalizowaniu tych informacji, czytaj dalej.
Jeśli masz przygotowane te informacje, możesz przeskakiwować, aby utworzyć sekcję żądania interfejsu API tego przewodnika Szybki start.
Wymagania wstępne
Zanim się zacznie, upewnij się, że masz:
Zainicjowane konto Intelligent Recommendations. Bardziej szczegółowe kroki procesu tworzenia konta Intelligent Recommendations można uzyskać w Utwórz nowe inteligentne konto Rekomendacji. Możesz również wykonać instrukcje w przewodniku Szybki start: Konfigurowanie i uruchamianie Intelligent Recommendations przy użyciu przykładowych danych.
Aplikacja (tożsamość Microsoft Entra) do wywoływania usługi Intelligent Recommendations.
Uwaga
Po pomyślnym inicjowaniu obsługi usługi może upłynieć jeden dzień na szkolenie w zakresie modelu uczenia maszynowego AI-ML w celu przetwarzania danych wejściowych i tworzenia list. Jeśli twoje pierwsze konto Intelligent Recommendations właśnie zaimprowizował, warto najpierw poczekać, aż zostanie kontynuowane.
Krok 1: Utwórz adres URL punktu końcowego
Każde konto Intelligent Recommendations wymaga co najmniej jednej usługi punkt końcowy do obsługi żądań. Usługa punkt końcowy unikatowego adresu URL służącego do wywoływania do usługi.
Aby utworzyć poprawne żądanie interfejsu API, znajdź adres URL punkt końcowy usługi przy użyciu konta portalu Azure:
Zaloguj się do Portalu Azure.
Przejdź do Konta Intelligent Recommendations.
Wybierz konto, o które chcesz zapytać.
Z sekcji Składniki w panelu menu wybierz punkty końcowe usługi.
Wybierz punkt końcowy usługi, którego chcesz użyć.
Znajdź adres URL we właściwościach punkt końcowy zasobu w następujący sposób:
Adres URL ma następującą strukturę:
https://{ir-account-name}-{service-endpoint-name}.mir.prod.reco.microsoft.com/
Krok 2: Konfigurowanie aplikacji klienta
Intelligent Recommendations wymagają uwierzytelniania OAuth2. Określ (lub utwórz) aplikację usługi Microsoft Entra, z której można wywołać usługę punkt końcowy uwierzytelniania. Nieuwierzyczone rozmowy kończą się niepowodzeniem i jest wyświetlany błąd.
Zaloguj się do Portalu Azure.
Przejdź do Tożsamość Microsoft Entra.
Przejdź do Rejestracja aplikacji.
Wybierz istniejącą aplikację lub utwórz nową.
Po przygotowaniu aplikacji należy we właściwościach aplikacji znaleźć identyfikator klienta i identyfikator dzierżawy:
Należy pamiętać o identyfikatorze klienta i identyfikatorze dzierżawcy. Te wartości są używane do utworzenia żądania interfejsu API.
Dodawanie dozwolonej tożsamości lub tożsamości do konta Intelligent Recommendations
Zanim będzie można kontynuować, należy dodać tożsamość do listy uwierzytelnienia na koncie Intelligent Recommendations.
- Zaloguj się do Portalu Azure.
- Przejdź do Konta Intelligent Recommendations.
- Wybierz konto, o które chcesz zapytać.
- Z menu wybierz Uwierzytelnianie punktów końcowych.
- Dodaj nowy główny identyfikator aplikacji (główny identyfikator jest taki sam jak identyfikator klienta, który został wcześniej znaleziony).
- Zmień typ główny na „Aplikacja”.
Uwaga
Aktualizacja tych ustawień może potrwać do 15 minut.
Krok 3: Konfigurowanie uwierzytelniania witryny
Ostatnim krokiem jest skonfigurowanie mechanizmu uwierzytelniania. Możesz użyć klucza tajnego lub certyfikatu. W tym przewodniku Szybki start zobaczysz, jak utworzyć wpis tajny.
- W lewym okienku nawigacji wybierz opcję Certyfikaty i klucze tajne.
- Wybierz pozycję Nowy wpis tajny klienta. Ta wartość jest prywatny i musi być przechowywana w bezpiecznym miejscu, ponieważ będzie potrzebna w następnym kroku.
Uwaga
Można skopiować wartość tylko po utworzeniu, tak jak pokazano: 
Po przygotowaniu niezbędnych informacji możesz utworzyć żądanie interfejsu API i wywołać usługę Intelligent Recommendations.
Skonstruuj żądanie API
Następna sekcja zawiera dwa sposoby wywołania interfejsu API Intelligent Recommendations za interfejs API REST narzędzi. Aby użyć innej aplikacji do wywołania punktu końcowego Intelligent Recommendations, upewnij się, że używasz narzędzia interfejsu API REST, które obsługuje uwierzytelnianie OAuth2.
W tym przewodniku Szybki start opisano sposób konfigurowania żądania interfejsu API w celu pobrania popularnej listy elementów zarówno z kodem Insomnia, jak i kodem C#.
Przed kontynuowaniem upewnij się, że spełnione są wszystkie następujące wymagania wstępne:
- Identyfikator dzierżawy w tożsamości Microsoft Entra
- Identyfikator klienta aplikacji wywołującego
- Tajna wartość aplikacji
- Zapytanie HTTP korzystające z adresu URL punktu końcowego obsługującego konto Intelligent Recommendations złożone z prawidłowej ścieżki/parametrów zapytania, zgodnie z opisem w interfejsie API Intelligent Recommendations
Uwaga
W następującym przykładowym żądaniu jest używamy nazwy konta irtest i nazwy usługi punktu końcowego serving01.
https://irtest-serving01.mir.prod.reco.microsoft.com/Reco/V1.0/Popular
Wywołaj punkt końcowy za pomocą Eksploratora wyników
WAŻNE : od kwietnia 2023 r. witryna internetowa portalu IR i narzędzie Eksplorator wyników są uznawane za przestarzałe i nie są już dostępne. Aby wyświetlić wyniki, użyj jednej z opcji w następujących sekcjach:
Wywołanie punktu końcowego za pomocą Insomnia
Możesz użyć narzędzia Insomnia lub podobnego narzędzia API REST, które obsługuje uwierzytelnianie OAuth2, aby wysyłać żądania testowe do punktu końcowego Intelligent Recommendations.
Aby uzyskać więcej szczegółowych informacji, zobacz temat Korzystanie z Insomnia z interfejsem Dataverse API sieci Web
Proces uwierzytelniania
W sekcji Wprowadzenie wybierz opcję Utwórz żądanie.
Przejdź do karty Autoryzacja kompozytora żądań i skonfiguruj ją za pomocą następujących wartości:
- Ustaw typ na OAuth 2.0
- Ustawianie nagłówków autoryzacji do nagłówków żądań
- Utwórz nowy token z nazwą tokena.
- Typ udzielania = Poświadczenia klienta
-
Adres URL tokena dostępu =
https://login.microsoftonline.com/<callerTenantID>/oauth2/v2.0/token - Identyfikator klienta = <yourAppClientID>
- Klucz tajny klienta = <yourAppSecretValue>
- Zakres = <URL twojego punktu końcowego>/.default
- Zachowaj uwierzytelnianie klienta ustawione na Wyślij jako podstawowy nagłówek uwierzytelniania
Oto jak to wygląda przed wygenerowaniem tokena:
Przewiń stronę w dół, aż znajdziesz przycisk Pobierz token dostępu. Jeśli skonfigurowany poprawnie, wybranie przycisku otwiera nowe okno z realnym tokenem.
Wybierz Użyj tokena.
Opublikuj prośbę
Teraz, gdy jesteś uwierzytelniony, możesz opublikować rzeczywiste żądanie.
Opublikuj żądanie, a następnie wybierz opcję Wyślij. W przewodniku przykładowych żądań zapoznaj się z listą dodatkowych wstępnie skonfigurowanych żądań interfejsu API, które można wypróbować.
Odpowiedź JSON pojawia się na dole ekranu:
Uwaga
Udana odpowiedź spowoduje zwrócenie listy elementów w sekcji Elementy odpowiedzi JSON. W tym scenariuszu najpopularniejszym identyfikatorem przedmiotu jest 712. Można tutaj wyświetlić pełną listę kodów stanów interfejsów API.
Wywoływanie punktu końcowego za pomocą kodu C#
Aby pomyślnie nawiązać połączenie z punktem końcowym Intelligent Recommendations przy użyciu języka C#, przygotuj następujące informacje:
- Identyfikator dzierżawy w tożsamości Microsoft Entra
- Identyfikator klienta aplikacji wywołującego
- Tajna wartość aplikacji
- Zapytanie HTTP korzystające z adresu URL punktu końcowego obsługującego konto Intelligent Recommendations złożone z prawidłowej ścieżki/parametrów zapytania, zgodnie z charakterystyką w interfejsie API Intelligent Recommendations
Następnie skopiuj poniższy przykładowy kod, zaktualizuj odpowiednie pola i wykonaj.
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); }
}
Udana odpowiedź zawiera listę zalecanych elementów opartą na scenariuszu w sekcji Elementy. W tym scenariuszu najpopularniejszym identyfikatorem przedmiotu jest 712. Można tutaj wyświetlić pełną listę kodów stanów interfejsów API.
Wywoływanie punktu końcowego za pomocą usługi Azure Machine Learning
Aby wykonać żądania interfejsu API w usłudze Intelligent Recommendations przy użyciu usługi Azure Machine Learning, można użyć tego produktu Retail Recommender Jupyter Notebook. Dodatkowa korzyść jest taka, że notebook zawiera również kroki łączenia usług Intelligent Recommendations i Azure Personalizer! Zobacz więcej: Aplikacja Jupyter Notebook o nazwie Retail Recommender.
Zobacz też
Odnośnik Intelligent Recommendations API
Kody statusu API
Przewodnik szybkiego startu: Skonfiguruj i uruchom Intelligent Recommendations z przykładowymi danymi
Omówienie wdrożenia
Używanie kontraktów danych do udostępniania danych