Creare e gestire gli invii

  • Articolo

Usare l'API di invio di Microsoft Store per eseguire query e creare invii a livello di codice per le app, i componenti aggiuntivi e i pacchetti in anteprima per il proprio account o per l'account della propria organizzazione. Questa API è utile se l'account gestisce molte app e componenti aggiuntivi e si desidera automatizzare e ottimizzare il processo di invio per queste risorse. Questa API usa Azure Active Directory (Azure AD) per autenticare le chiamate dall'app o dal servizio.

I passaggi seguenti descrivono il processo end-to-end di uso dell'API di invio di Microsoft Store:

  1. Assicurarsi di aver completato tutti i prerequisiti.
  2. Prima di chiamare un metodo nell'API di invio di Microsoft Store, ottenere un token di accesso di Azure AD. Dopo aver ottenuto un token, hai 60 minuti per usare questo token nelle chiamate all'API di invio a Microsoft Store prima della scadenza del token. Dopo la scadenza del token, è possibile generarne uno nuovo.
  3. Chiamare l'API di invio di Microsoft Store.

Importante

Se si usa questa API per creare un invio per un'app, per un pacchetto in anteprima o per componente aggiuntivo, assicurarsi di apportare le ulteriori modifiche all'invio esclusivamente mediante l'API, anziché nel Centro per i partner. Se si usa il Centro per i partner per modificare un invio creato originariamente usando l'API, non sarà più possibile modificare l'invio o eseguirne il commit mediante l'API. In alcuni casi, l'invio potrebbe restare in uno stato di errore in cui il processo di invio non può continuare. In questo caso, è necessario eliminare l'invio e creare un nuovo invio.

Importante

Non è possibile usare questa API per pubblicare invii per acquisti in volumi elevati tramite Microsoft Store per le aziende e Microsoft Store per la formazione né per pubblicare invii per app line-of-business direttamente nelle aziende. In entrambi questi scenari, è necessario pubblicare l'invio nel Centro per i partner.

Nota

Questa API non può essere usata con app o componenti aggiuntivi che usano aggiornamenti obbligatori delle app e componenti aggiuntivi consumable gestiti dallo Store. Se si usa l'API di invio di Microsoft con un'app o un componente aggiuntivo che usa una dei queste funzionalità, l'API restituirà un codice di errore 409. In questo caso, è necessario usare il Centro per i partner per gestire gli invii per l'app o il componente aggiuntivo.

Passaggio 1: completare i prerequisiti per l'uso dell'API di invio di Microsoft Store

Prima di iniziare a scrivere il codice per chiamare l'API di invio di Microsoft Store, verificare di aver completato i prerequisiti seguenti.

  • L'utente o l'organizzazione deve disporre di una directory di Azure AD e dell'autorizzazione come amministratore aziendale per la directory. Se si usa già Microsoft 365 o altri servizi aziendali Microsoft, si dispone già di una directory di Azure AD. In caso contrario, è possibile creare una nuova directory di Azure AD nel Centro per i partner senza costi aggiuntivi.

  • È necessario associare un'applicazione Azure AD all'account del Centro per i partner e ottenere l'ID tenant, l'ID client e la chiave. Questi valori sono necessari per ottenere un token di accesso di Azure AD, che sarà usato nelle chiamate all'API di invio di Microsoft Store.

  • Preparare l'app per l'uso con l'API di invio di Microsoft Store:

    • Se l'app non esiste ancora nel Centro per i partner, è necessario crearla riservandone il nome nel Centro per i partner. Non è possibile usare un API di invio di Microsoft Store per creare un'app nel Centro per i partner. È necessario lavorare nel Centro per i partner per crearla e quindi è possibile usare l'API per accedere all'app e creare invii per essa a livello di codice. Tuttavia, è possibile usare l'API per creare componenti aggiuntivi e pacchetti in anteprima a livello di codice prima di creare invii per essi.

    • Per poter creare un invio per una determinata app usando questa API, è innanzitutto necessario creare un invio per 'app nel Centro per i partner, includendo le risposte al questionario sulle classificazioni in base all'età. Dopo aver eseguito questa operazione, sarà possibile creare nuovi invii a livello di codice per questa app usando l'API. Non è necessario creare un invio di componente aggiuntivo o di pacchetto in anteprima prima di usare l'API per questi tipi di invii.

    • Se si sta creando o aggiornando un invio di un'app ed è necessario includere un pacchetto dell'app, preparare il pacchetto dell'app.

    • Se si sta creando o aggiornando un invio di un'app ed è necessario includere screenshot o immagini per la presentazione nello Store, preparare gli screenshot e le immagini dell'app.

    • Se si sta creando o aggiornando un invio di un componente aggiuntivo ed è necessario includere un'icona, preparare l'icona.

Procedura di associazione di un'applicazione Azure AD all'account del Centro per i partner

Per poter usare l'API di invio di Microsoft Store, è necessario associare un'applicazione Azure AD al proprio account del Centro per i partner, recuperare l'ID tenant e l'ID client per l'applicazione e generare una chiave. L'applicazione Azure AD rappresenta l'app o il servizio da cui si vuole chiamare l'API di invio di Microsoft Store. Per ottenere un token di accesso di Azure AD da passare all'API, sono necessari l'ID tenant, l'ID client e la chiave.

Nota

È sufficiente eseguire questa attività una sola volta. Quando si dispone di ID tenant, ID client e chiave, è possibile riutilizzarli ogni volta che è necessario creare un nuovo token di accesso Azure AD.

  1. Nel Centro per i partner, associare l'account del Centro per i partner dell'organizzazione alla directory di Azure AD dell'organizzazione.

  2. Quindi, dalla pagina Utenti nella sezione Impostazioni account del Centro per i partner, aggiungere l'applicazione Azure AD che rappresenta l'app o il servizio che verrà usato per accedere agli invii per l'account del Centro per i partner. Assicurarsi di assegnare a questa applicazione il ruolo di Manager. Se l'applicazione non esiste ancora nella directory di Azure AD, è possibile creare una nuova applicazione Azure AD nel Centro per i partner.

  3. Tornare alla pagina Utenti, fare clic sul nome dell'applicazione Azure AD per passare alle impostazioni e copiare i valori di ID tenant e ID client.

  4. Fare clic su Aggiungi nuova chiave. Nella schermata seguente, copiare il valore della chiave. Non sarà più possibile accedere a queste informazioni dopo aver lasciato la pagina. Per altre informazioni, vedi Gestire le chiavi per un'applicazione Azure AD.

Passaggio 2: ottenere un token di accesso di Azure AD

Prima di chiamare un metodo nell'API di invio di Microsoft Store, è necessario ottenere un token di accesso di Azure AD da passare all'intestazione Autorizzazione di ogni metodo nell'API. Dopo aver ottenuto un token di accesso, questo sarà disponibile per 60 minuti prima della scadenza. Dopo la scadenza del token, è possibile aggiornarlo in modo da continuare a usarlo nelle successive chiamate all'API.

Per ottenere il token di accesso, seguire le istruzioni riportate in Chiamate da servizio a servizio mediante le credenziali client per inviare un HTTP POST all'endpoint https://login.microsoftonline.com/<tenant_id>/oauth2/token. Di seguito è riportata una richiesta di esempio.

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://manage.devcenter.microsoft.com

Per il valore tenant_id in POST URI e per i parametri client_id e client_secret, specificare l'ID tenant, l'ID client e la chiave per l'applicazione recuperati dal Centro per i partner nella sezione precedente. Per il parametro resource è necessario specificare https://manage.devcenter.microsoft.com.

Dopo la scadenza del token di accesso, è possibile recuperarne uno nuovo eseguendo di nuovo la stessa chiamata HTTP.

Per esempi che illustrano come ottenere un token di accesso usando codice C#, Java o Python, vedere gli esempi di codice dell'API di invio di Microsoft Store.

Passaggio 3: usare l''API di invio di Microsoft Store

Una volta che si dispone di un token di accesso di Azure AD, è possibile chiamare i metodi nell'API di invio di Microsoft Store. L'API include molti metodi raggruppati in scenari per app, componenti aggiuntivi e pacchetti in anteprima. Per creare o aggiornare gli invii, in genere si chiamano più metodi nell'API di invio di Microsoft Store in un ordine specifico. Per informazioni su ogni scenario e sulla sintassi di ogni metodo, vedere gli articoli nella tabella seguente.

Nota

Dopo aver ottenuto un token di accesso, si hanno 60 minuti per chiamare i metodi nell'API di invio di Microsoft Store prima della scadenza del token.

Scenario Descrizione
App Recuperare i dati per tutte le app registrate nel proprio account del Centro per i partner e creare invii per le app. Per ulteriori informazioni su questi metodi, vedere gli articoli seguenti:
Componenti aggiuntivi Ottenere, creare o eliminare componenti aggiuntivi per le app e quindi ottenere, creare o eliminare invii per i componenti aggiuntivi. Per ulteriori informazioni su questi metodi, vedere gli articoli seguenti:
Pacchetti in anteprima Ottenere, creare o eliminare pacchetti in anteprima per le app e quindi ottenere, creare o eliminare invii per i pacchetti in anteprima. Per ulteriori informazioni su questi metodi, vedere gli articoli seguenti:

Esempi di codice

Gli articoli seguenti forniscono esempi di codice dettagliati che illustrano come usare l'API di invio di Microsoft Store in diversi linguaggi di programmazione:

Modulo PowerShell StoreBroker

In alternativa alla chiamata diretta dell'API di invio di Microsoft Store, è anche disponibile modulo PowerShell open source che implementa un'interfaccia della riga di comando sull'API. Questo modulo è denominato StoreBroker. È possibile usare questo modulo per gestire gli invii di app, di pacchetti in anteprima e di componenti aggiuntivi dalla riga di comanda anziché chiamare direttamente l'API di invio di Microsoft Store. In alternativa, è possibile semplicemente esplorare il codice sorgente per vedere altri esempi di come chiamare questa API. Il modulo StoreBroker è usato attivamente in Microsoft come metodo principale per l'invio di molte applicazioni proprietarie allo Store.

Per ulteriori informazioni, vedere la pagina su StoreBroker in GitHub.

Risoluzione dei problemi

Problema Risoluzione
Dopo che si chiama l'API di invio di Microsoft Store da PowerShell, i dati di risposta per l'API vengono danneggiati se li si converte dal formato JSON a un oggetto PowerShell usando il cmdlet ConvertFrom-Json e poi nuovamente al formato JSON usando il cmdlet ConvertTo-Json. Per impostazione predefinita, il parametro -Depth del cmdlet ConvertTo-Json è impostato su 2 livelli di oggetti e questa profondità è insufficiente per la maggior parte degli oggetti JSON restituiti dall'API di invio di Microsoft Store. Quando si chiama il cmdlet ConvertTo-Json, impostare il parametro -Depth su un numero maggiore, ad esempio 20.

Informazioni aggiuntive

Per eventuali domande sull'API di invio di Microsoft Store o per assistenza nella gestione degli invii con questa API, usare le risorse seguenti:

  • Porre le domande sui nostri forum.
  • Visitare la nostra pagina di supporto e richiedere una delle opzioni di assistenza del Centro per i partner. Se viene richiesto di scegliere un tipo di problema e una categoria, scegliere rispettivamente Invio e certificazione di un'app e Invio di un'app.