Condividi tramite

Guida rapida: effettuare una chiamata API autenticata

  • Articolo

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:

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:

  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:

    Individua l'URL dell'endpoint di servizio nelle proprietà della risorsa endpoint.

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:

    Individuare l'ID client e l'ID tenant nelle proprietà dell'applicazione Microsoft Entra ID.

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

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.

  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.

Nota

Puoi solo copiare il valore segreto direttamente dopo la creazione, come mostrato in: Copia il segreto dell'applicazione.

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

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

  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:

    Esempio di modulo di autorizzazione compilato.

  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.

    Esempio di un token di accesso corretto.

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:

    Esempio di risultati restituiti quando si effettua una richiesta API popolare.

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:

  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