Guida rapida: effettuare una chiamata API autenticata
Questo articolo ti aiuta a costruire una richiesta autenticata al servizio Raccomandazioni intelligenti e a vedere i risultati.
Descrizione
Per effettuare una richiesta API corretta, è necessario preparare le seguenti informazioni:
- ID tenant di Microsoft Entra ID
- ID client dell'applicazione del chiamante
- Valore del segreto dell'applicazione
- La query HTTP che utilizza l'account Raccomandazioni intelligenti che fornisce l'URL endpoint composto da percorsi/parametri di query validi, come indicato nell'API di Raccomandazioni intelligenti.
Per aiuto con l'individuazione di queste informazioni, continua a leggere.
Se hai preparato queste informazioni, puoi saltare alla sezione Costruire la richiesta API di questa guida rapida.
Prerequisiti
Prima di iniziare, verifica di disporre di:
Un account Raccomandazioni intelligenti sottoposto a provisioning. Se non hai creato un account Raccomandazioni intelligenti, vai a Creare un nuovo account Raccomandazioni intelligenti. Puoi anche seguire le istruzioni in Guida rapida: impostare ed eseguire Raccomandazioni intelligenti con i dati di esempio.
Un'applicazione (identità Microsoft Entra ID) per chiamare il servizio Raccomandazioni intelligenti.
Nota
Una volta eseguito il provisioning del servizio, potrebbe essere necessario fino a un giorno prima che il training del modello IA-ML elabori i dati di input e produca elenchi classificati. Se hai appena eseguito il provisioning del tuo primo account Raccomandazioni intelligenti, potresti voler attendere prima di continuare.
Passaggio 1: creare l'URL dell'endpoint
Ogni account Raccomandazioni intelligenti richiede almeno un endpoint di servizio per soddisfare le richieste. Un endpoint di servizio fornisce un URL univoco per chiamare il servizio.
Per creare una richiesta API corretta, individua l'URL dell'endpoint di servizio usando l'account del portale di Azure:
Accedi al portale di Azure.
Passa agli Account di Raccomandazioni intelligenti.
Seleziona l'account su cui vuoi eseguire la query.
Dalla sezione Componenti del menu seleziona Endpoint di servizio.
Seleziona l'endpoint di servizio che desideri utilizzare.
Individua l'URL nelle proprietà della risorsa endpoint, come mostrato:
L'URL è strutturato come segue:
https://{ir-account-name}-{service-endpoint-name}.mir.prod.reco.microsoft.com/
Passaggio 2: configurare un'applicazione client
Raccomandazioni intelligenti richiede un'autenticazione OAuth2. Determina (o crea) l'applicazione Microsoft Entra ID da cui chiamare l'endpoint di servizio con autenticazione. Qualsiasi chiamata non autenticata ha esito negativo con un errore.
Accedi al portale di Azure.
Vai a Microsoft Entra ID.
Vai a Registrazioni app.
Seleziona un'applicazione esistente o creane una nuova.
Una volta che l'applicazione è pronta, individua l'ID client e l'ID tenant nelle proprietà dell'applicazione:
Prendi nota dell'ID cliente e dell'ID tenant. Questi valori vengono utilizzati per creare la richiesta API.
Aggiungere l'identità o le identità consentite all'account Raccomandazioni intelligenti
Prima di continuare, devi aggiungere l'identità all'elenco autenticato nel tuo account Raccomandazioni intelligenti.
- Accedi al portale di Azure.
- Passa agli Account di Raccomandazioni intelligenti.
- Seleziona l'account su cui vuoi eseguire la query.
- Dal menu seleziona Autenticazioni endpoint.
- Aggiungi il nuovo ID entità di sicurezza dell'applicazione (l'ID entità di sicurezza è l'ID client, che hai trovato in precedenza).
- Modifica il tipo di entità servizio in "Applicazione".
Nota
L'aggiornamento di queste impostazioni può richiedere fino a 15 minuti.
Passaggio 3: configurare l'autenticazione
L'ultimo passaggio consiste nel configurare il meccanismo di autenticazione. È possibile utilizzare un segreto o un certificato. In questa guida rapida puoi vedere come si crea un segreto.
- Nel riquadro di spostamento a sinistra, seleziona Certificati e segreti.
- Seleziona Nuovo segreto client. Questo valore segreto è privato e deve essere archiviato in un luogo sicuro, perché ti servirà nel prossimo passaggio.
Nota
Puoi solo copiare il valore segreto direttamente dopo la creazione, come mostrato in:
Ora che hai preparato le informazioni necessarie, sei pronto per creare una richiesta API e chiamare il servizio Raccomandazioni intelligenti.
Costruire la richiesta API
Nella prossima sezione vengono forniti due modi per chiamare l'API Raccomandazioni intelligenti con gli strumenti API REST. Per utilizzare un'applicazione diversa per chiamare l'endpoint di Raccomandazioni intelligenti, assicurati di utilizzare uno strumento API REST che supporti l'autenticazione OAuth2.
In questa guida introduttiva, illustreremo come configurare una richiesta API per recuperare un elenco popolare di articoli sia con Insomnia che con codice C#.
Prima di continuare, assicurati di avere ciascuno dei seguenti prerequisiti:
- ID tenant di Microsoft Entra ID
- ID client dell'applicazione del chiamante
- Valore del segreto dell'applicazione
- La query HTTP che utilizza l'account Raccomandazioni intelligenti che fornisce l'URL endpoint composto da percorsi/parametri di query validi, come indicato nell'API di Raccomandazioni intelligenti
Nota
Nella seguente richiesta di esempio, stiamo usando il nome dell'account irtest e il servizio endpoint serve01.
https://irtest-serving01.mir.prod.reco.microsoft.com/Reco/V1.0/Popular
Chiamare l'endpoint con Esplora risultati
IMPORTANTE Il sito Web del portale IR e lo strumento Esplora risultati sono stati deprecati a partire da aprile 2023 e non sono più in uso. Per visualizzare i risultati, utilizza una delle opzioni nelle seguenti sezioni:
Chiamata all'endpoint con Insomnia
Puoi utilizzare Insomnia o uno strumento simile API REST che supporti l'autenticazione OAuth2 per inviare richieste di test a un endpoint di Raccomandazioni intelligenti.
Per maggiori dettagli, vedi Utilizzare Insomnia con l'API Web Dataverse
Processo di autenticazione
Nella sezione Attività iniziali, seleziona Crea una richiesta.
Passa alla scheda Autorizzazione del compositore di richieste e configurarla con i seguenti valori:
- Imposta tipo su OAuth 2.0
- Imposta Aggiungi intestazioni di autorizzazione su Richiedi intestazioni
- Crea un nuovo token con un nome.
- Tipo di concessione = Credenziali client
-
URL del token di accesso =
https://login.microsoftonline.com/<callerTenantID>/oauth2/v2.0/token
- ID client = <yourAppClientID>
- Segreto client = <yourAppSecretValue>
- Ambito = <IL TUO URL ENDPOINT>/.default
- Mantieni Autenticazione client impostato su Invia come intestazione di autenticazione di base
Ecco come appare prima della generazione del token:
Scorri la pagina fino a trovare il pulsante Ottieni nuovo token di accesso. Se configurato correttamente, selezionando il pulsante si apre una nuova finestra con un token valido.
Seleziona Usa Token.
Registrare la richiesta
Ora che sei autenticato, puoi registrare la richiesta effettiva.
Registra la tua richiesta, quindi seleziona Invia. Consulta la nostra Guida alle richieste di esempio per un elenco di ulteriori richieste API preconfigurate che puoi provare.
La risposta JSON appare nella parte inferiore dello schermo:
Nota
Una risposta positiva restituirà un elenco classificato di articoli nella sezione Articoli della risposta JSON. Per questo scenario, l'ID articolo più popolare è 712. È possibile visualizzare l'elenco completo dei codici di stato API qui.
Chiamata all'endpoint con codice C#
Per effettuare una chiamata corretta all'endpoint Raccomandazioni intelligenti utilizzando C#, prepara le seguenti informazioni:
- ID tenant di Microsoft Entra ID
- ID client dell'applicazione del chiamante
- Valore del segreto dell'applicazione
- La query HTTP che utilizza l'account Raccomandazioni intelligenti che fornisce l'URL endpoint composto da percorsi/parametri di query validi, come indicato nella specifica API di Raccomandazioni intelligenti
Quindi, copia il codice di esempio seguente, aggiorna i campi pertinenti ed esegui.
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); }
}
Una risposta positiva contiene un elenco classificato di articoli consigliati in base allo scenario sotto la sezione Articoli. Per questo scenario, l'ID articolo più popolare è 712. È possibile visualizzare l'elenco completo dei codici di stato API qui.
Chiamare l'endpoint con Azure Machine Learning
Per effettuare richieste API al servizio Raccomandazioni intelligenti usando Azure Machine Learning, puoi usare questo Jupyter Notebook Retail Recommender. Come bonus aggiuntivo, il notebook include anche i passaggi per combinare Raccomandazioni intelligenti con Personalizza esperienze di Azure. Ulteriori informazioni: Jupyter Notebook di Retail Recommender
Vedi anche
Riferimento dell'API di Raccomandazioni intelligentiCodici di stato dell'APIGuida rapida: impostare ed eseguire Raccomandazioni intelligenti con dati di esempioPanoramica della distribuzioneUtilizzare i contratti dati per condividere i dati