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.

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:

1. Accedi al portale di Azure.

2. Passa agli Account di Raccomandazioni intelligenti.

3. Seleziona l'account su cui vuoi eseguire la query.

4. Dalla sezione Componenti del menu seleziona Endpoint di servizio.

5. Seleziona l'endpoint di servizio che desideri utilizzare.

6. 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.

1. Accedi al portale di Azure.

2. Vai a Microsoft Entra ID.

3. Vai a Registrazioni app.

4. Seleziona un'applicazione esistente o creane una nuova.

5. Una volta che l'applicazione è pronta, individua l'ID client e l'ID tenant nelle proprietà dell'applicazione:

   

6. 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.

1. Accedi al portale di Azure.
2. Passa agli Account di Raccomandazioni intelligenti.
3. Seleziona l'account su cui vuoi eseguire la query.
4. Dal menu seleziona Autenticazioni endpoint.
5. Aggiungi il nuovo ID entità di sicurezza dell'applicazione (l'ID entità di sicurezza è l'ID client, che hai trovato in precedenza).
6. Modifica il tipo di entità servizio in "Applicazione".

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.

1. Nel riquadro di spostamento a sinistra, seleziona Certificati e segreti.
2. Seleziona Nuovo segreto client. Questo valore segreto è privato e deve essere archiviato in un luogo sicuro, perché ti servirà nel prossimo passaggio.

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:

1. ID tenant di Microsoft Entra ID
2. ID client dell'applicazione del chiamante
3. Valore del segreto dell'applicazione
4. 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

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

1. Nella sezione Attività iniziali, seleziona Crea una richiesta.

2. 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:

   

3. 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.

4. Seleziona Usa Token.

   

Registrare la richiesta

Ora che sei autenticato, puoi registrare la richiesta effettiva.

1. 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.

2. La risposta JSON appare nella parte inferiore dello schermo:

   

Chiamata all'endpoint con codice C#

Per effettuare una chiamata corretta all'endpoint Raccomandazioni intelligenti utilizzando C#, prepara le seguenti informazioni:

1. ID tenant di Microsoft Entra ID
2. ID client dell'applicazione del chiamante
3. Valore del segreto dell'applicazione
4. 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 intelligenti
Codici di stato dell'API
Guida rapida: impostare ed eseguire Raccomandazioni intelligenti con dati di esempio
Panoramica della distribuzione
Utilizzare i contratti dati per condividere i dati