Condividi tramite

Gestire gli utili usando l'API del Servizio di Utili

Questo articolo illustra come accedere ai dati sugli utili tramite le API utili anziché l'interfaccia utente del Centro per i partner. Queste API offrono un modo programmatico per offrire la funzionalità Esporta dati nel Centro per i partner.

Importante

Azure Active Directory (Azure AD) Graph non sarà più supportato a partire dal 30 giugno 2023. In futuro non verranno effettuati ulteriori investimenti in Azure AD Graph. Le API Graph di Azure AD non hanno alcun contratto di servizio o impegno di manutenzione oltre alle correzioni correlate alla sicurezza. Investimenti nelle nuove funzionalità e caratteristiche verranno effettuati solo in Microsoft Graph.

Azure AD Graph verrà ritirato nei passaggi incrementali in modo da avere tempo sufficiente per eseguire la migrazione delle applicazioni alle API Di Microsoft Graph. A una data successiva che verrà annunciata, si bloccherà la creazione di nuove applicazioni usando Azure AD Graph.

Per altre informazioni, vedere Importante: Ritiro di Azure AD Graph e Disapprovazione del modulo PowerShell.

API disponibili

Vedi tutte le API disponibili in Proventi dei partner.

Prerequisiti

  • Avere una sottoscrizione funzionante nel portale di Azure.
  • Avere accesso a un Web browser.
  • Essere in grado di effettuare chiamate API REST, a livello di codice o tramite software dedicato.

Registrare un'applicazione con Microsoft Identity Platform

  1. Seguire le istruzioni per creare una registrazione dell'app con Microsoft Identity Platform.

  2. Assegnare all'app i permessi delegati appropriati.

    1. Nella registrazione dell'app appena creata passare a Gestisci autorizzazioni API →. Selezionare "Aggiungi un'autorizzazione". Screenshot che mostra il pulsante Aggiungi un'autorizzazione.
    2. Selezionare la scheda "API usate dall'organizzazione", quindi cercare AppId "4990cffe-04e8-4e8b-808a-1175604b879f" o per nome "Microsoft Dev Center". Per le autorizzazioni, selezionare "user_impersonation". Selezionare "Aggiungi autorizzazioni".
      • Risoluzione dei problemi: se la ricerca dell'API di Dev Center non restituisce risultati, potrebbe essere necessario creare manualmente le entità servizio necessarie per accedere a queste API. Possono essere creati con AzCLI: 
        az ad sp create --id 4990cffe-04e8-4e8b-808a-1175604b879f
        Successivamente, le autorizzazioni API devono essere disponibili per la selezione dalla finestra di dialogo di ricerca. Screenshot che mostra l'autorizzazione user_impersonation.
    3. In aggiunta, assicurarsi che l'app disponga di un'autorizzazione "User.Read" in Microsoft Graph. In caso contrario, aggiungerlo selezionando Microsoft Graph nella scheda API Microsoft.
    4. Selezionare "Concedi consenso amministratore" per tutte e tre le autorizzazioni ottenute.
    5. Le autorizzazioni dell'app devono essere simili alle seguenti (prendere nota del segno di spunta verde accanto a ogni autorizzazione): screenshot che mostra l'elenco delle autorizzazioni necessarie con il consenso amministratore concesso.

  3. Configurare un URI di reindirizzamento per la piattaforma Web.

    1. Passare a Gestisci autenticazione →. Selezionare "Aggiungi una piattaforma". Screenshot che mostra il pulsante Aggiungi una piattaforma.
    2. Selezionare "Web".
    3. In URI di reindirizzamento immettere l'URI che si vuole usare per l'applicazione, ad esempio https://localhost:3000. Annotare questo URI per un secondo momento. Premere "Configura". Screenshot che mostra la scheda URI di reindirizzamento con un URI di esempio della porta 3000 in localhost.

  4. Generare un segreto client da usare per ottenere i token di accesso.

    1. Passare a Gestisci → certificati e segreti. Passare alla scheda "Segreti client", selezionare "Nuovo segreto client". Screenshot che mostra il pulsante Aggiungi un segreto client.
    2. Immettere il nome e la durata desiderati.
    3. Selezionare Aggiungi segreto.
    4. Registrare il valore altrove. Assicurati di mantenerlo in una posizione sicura, ad esempio un archivio di chiavi. Questo segreto viene usato quando si richiedono AccessToken e RefreshToken.

Ottenere il token di accesso - Account abilitati per MFA

Le API dei guadagni richiedono che venga fornito un AccessToken come token di autorizzazione nella richiesta, con il prefisso Bearer <access-token> nell'intestazione Autorizzazione. È possibile ottenere questo token accedendo con il proprio account; Tuttavia, i token di accesso sono di breve durata. L'accesso a un account abilitato per l'autenticazione a più fattori per generare un token ogni volta che è necessario chiamare l'API non è pratico per i flussi di lavoro che coinvolgono l'automazione. Questi passaggi illustrano il processo per generare un RefreshToken. Ha una durata più lunga (circa 3 mesi) e può essere usata per ottenere AccessToken. Archiviando un RefreshToken in una posizione sicura, è possibile usarlo per ottenere un AccessToken programmaticamente per chiamare l'API dei Guadagni. Nota: RefreshToken può essere usato una sola volta, dopo di che diventa obsoleto. Nella risposta viene restituito un nuovo refreshToken insieme a AccessToken. Assicurarsi di sostituire il valore precedente di RefreshToken nella memoria sicura ogni volta che si usa RefreshToken.

  1. Ottenere AuthCode tramite browser. Attualmente, questo processo deve essere eseguito usando l'interfaccia utente di un Web browser e non può essere eseguito a livello di codice.

    1. Seguire il modello qui per compilare un URL usato per recuperare AuthCode.
      1. Usare l'ID tenant e l'ID client per l'applicazione creata.
      2. Impostare l'ambito su https://api.partner.microsoft.com/.default.
      3. Imposta l'URL di reindirizzamento sull'URL configurato in precedenza per il reindirizzamento. Il modello di URL è: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize?client_id=<client-id>&response_type=code&redirect_uri=<redirect-uri>&scope=https%3A%2F%2Fapi.partner.microsoft.com%2F.default
    2. Passare all'URL compilato e accedere usando le credenziali di un utente autorizzato.
    3. Al termine dell'accesso, il browser tenta di aprire un URL con il formato <redirect-uri>/?code=<auth-code>&session_state=<state-id>#. Per l'esempio di URI di reindirizzamento in un passaggio precedente, l'URL a cui viene inviato deve essere https://localhost:3000/?code=<auth-code>?session_state=<state-id>#. Salvare il codice AuthCode restituito in un punto sicuro.
      • Poiché in genere non è presente alcuna app in ascolto su localhost:3000, il browser restituisce un messaggio di errore "impossibile connettersi". Questo errore è previsto, poiché è sufficiente copiare manualmente il valore AuthCode dal parametro di code query URL illustrato in precedenza.
      • In una soluzione di produzione, è possibile creare un'app che gestisca automaticamente questa parte del processo di autenticazione. Ad esempio, può trattarsi di un flusso di lavoro in cui l'utente passa a un'applicazione a pagina singola . L'utente seleziona un pulsante di accesso che li porta all'URL costruito in precedenza. Al momento dell'accesso, la SPA (Single Page Application) estrae il valore di AuthCode e lo salva in un archivio. L'applicazione a pagina singola usa quindi AuthCode per ottenere RefreshToken e AccessToken, come descritto nei passaggi successivi.

  2. Usare AuthCode per ottenere RefreshToken e AccessToken iniziale. Nota: RefreshToken scade ogni 3 mesi e deve essere ottenuto nuovamente e archiviato in un key vault.

    1. Compilare una richiesta API POST seguendo il modello fornito qui.
      1. Usare gli stessi valori per l'ID tenant/client e l'URL di reindirizzamento.
      2. Impostare l'ambito su https://api.partner.microsoft.com/.default offline_access.
      3. Impostare il codice su AuthCode ottenuto nel passaggio precedente.
      4. Impostare client_secret sul segreto generato per l'applicazione creata. L'URL deve quindi essere strutturato come segue: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

  3. In un secondo momento, è possibile usare RefreshToken per ottenere un nuovo accessToken.

    1. Compilare una richiesta API POST seguendo il modello fornito qui.
      1. Usare gli stessi valori per l'ID tenant/client e l'URL di reindirizzamento.
      2. Impostare l'ambito su https://api.partner.microsoft.com/.default
      3. Impostare refresh_token su RefreshToken ottenuto nel passaggio precedente
      4. Impostare client_secret sul segreto generato per l'applicazione creata.

Ottenere il token di accesso - Account non MFA

  1. Ottenere AccessToken usando le informazioni per la registrazione della nuova app.
    1. Compilare una richiesta API POST seguendo il modello fornito qui.
      1. Usare gli stessi valori per l'ID tenant/client
      2. Impostare l'ambito su https://api.partner.microsoft.com/.default
      3. Usare il nome utente/password per un utente autorizzato. L'URL deve quindi essere strutturato come segue: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
    2. La richiesta restituisce AccessToken e un nuovo refreshToken. Assicurarsi di aggiornare il valore archiviato per RefreshToken, perché non è più possibile usare il valore precedente.

Guadagni da chiamate (precedentemente nota come transactionhistory)/Pagamenti

Contenuti correlati

  • Last updated on