Gestire gli invii di pacchetti in anteprima

  • Articolo

L'API di invio di Microsoft Store fornisce metodi che puoi usare per gestire gli invii dei pacchetti di distribuzione per le tue app, incluse le implementazioni graduali dei pacchetti. Per un'introduzione all'API di invio di Microsoft Store, inclusi i prerequisiti per l'utilizzo dell'API, vedereCrea e gestisci invii utilizzando i servizi di Microsoft Store.

Importante

Se usi l'API di invio di Microsoft Store per creare un invio per un pacchetto di distribuzione, assicurati di apportare ulteriori modifiche all'invio solo utilizzando l'API anziché il Centro per i partner. Se utilizzi il pannello di controllo per modificare un invio creato originariamente utilizzando l'API, non potrai più modificare o confermare tale invio utilizzando l'API. In alcuni casi, l'invio potrebbe rimanere in uno stato di errore in cui non è possibile procedere nel processo di invio. In tal caso, è necessario eliminare l'invio e crearne uno nuovo.

Metodi per gestire l'invio dei pacchetti di distribuzione.

Utilizzare i seguenti metodi per ottenere, creare, aggiornare, confermare o eliminare l'invio di un pacchetto di distribuzione. Prima di poter utilizzare questi metodi, il pacchetto di distribuzione deve già esistere nell'account del Centro partner. È possibile creare un pacchetto di distribuzione nel Centro per i partner definendo il tipo di prodotto e l'ID prodotto o utilizzando i metodi API di invio di Microsoft Store descritti in Gestisci pacchetti di distribuzione.

Method URI Descrizione
GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Ottieni un invio di un pacchetto di distribuzione esistente
GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status Ottieni lo stato dell'invio di un pacchetto di distribuzione esistente
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions Crea un nuovo invio di un pacchetto di distribuzione
PUT https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Aggiorna un invio di un pacchetto di distribuzione esistente
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit Effettua l'invio di un pacchetto di distribuzione nuovo o aggiornato
DELETE https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Cancella un nuovo invio di un pacchetto di distribuzione

Creare un invio di pacchetto in anteprima

Per creare un invio per un pacchetto di distribuzione, seguire questa procedura.

  1. Se non lo hai ancora fatto, completa i prerequisiti descritti n Crea e gestisci invii utilizzando i servizi di Microsoft Store, inclusa l'associazione di un'applicazione Azure AD al tuo account del Centro per i partner e l'ottenimento dell'ID client e della chiave. Devi farlo solo una volta; dopo aver ottenuto l'ID client e la chiave, è possibile riutilizzarli ogni volta che è necessario creare un nuovo token di accesso di Azure AD.

  2. Ottieni un token di accesso di Azure AD. Devi passare questo token di accesso ai metodi nell'API di invio di Microsoft Store. Dopo aver ottenuto un token di accesso, questo sarà disponibile per 60 minuti prima della scadenza. Dopo la scadenza del token, è possibile ottenerne uno nuovo.

  3. Crea l'invio di un pacchetto di distribuzione eseguendo il metodo seguente nell'API di invio di Microsoft Store. Questo metodo crea un nuovo invio in corso, che è una copia dell'ultimo invio pubblicato.

    POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions

    Il corpo della risposta contiene un file invio distribuzione risorsa che include l'ID del nuovo invio, l'URI della firma di accesso condiviso (SAS) per il caricamento di ogni pacchetto per l'invio ad Archiviazione BLOB di Azure e tutti i dati per il nuovo invio (inclusi tutti glli elenchi e le informazioni sui prezzi ).

    Nota

    Un URI SAS fornisce l'accesso a una risorsa sicura nell'archiviazione di Azure senza richiedere chiavi dell'account. Per informazioni di base sugli URI SAS e sul relativo utilizzo con Archiviazione BLOB di Azure, vedere Firme di accesso condiviso, parte 1: comprensione del modello SAS e Firme di accesso condiviso, parte 2: creare e usare una firma di accesso condiviso con l'archiviazione BLOB.

  4. Se stai aggiungendo nuovi pacchetti per l'invio prepara i pacchetti e aggiungili a un archivio ZIP.

  5. Rivedere idati di invio della distribuzione con le eventuali modifiche richieste per il nuovo invio ed eseguire il seguente metodo per aggiornare l'invio del pacchetto di distribuzione.

    PUT https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}

    Nota

    Se stai aggiungendo nuovi pacchetti per l'invio, assicurati di aggiornare i dati di invio per fare riferimento al nome e al percorso relativo di questi file nell'archivio ZIP.

  6. Se stai aggiungendo nuovi pacchetti per l'invio, carica l'archivio ZIP su Azure Blob Storage utilizzando l'URI SAS fornito nel corpo della risposta del metodo POST chiamato in precedenza. Esistono diverse librerie di Azure che puoi usare per eseguire questa operazione su una varietà di piattaforme, tra cui:

    Nell'esempio di codice C# seguente viene illustrato come caricare un archivio ZIP nell'archiviazione BLOB di Azure utilizzando la classe CloudBlockBlob nella libreria client di archiviazione di Azure per .NET. Questo esempio presuppone che l'archivio ZIP sia già stato scritto in un oggetto flusso.

    string sasUrl = "https://productingestionbin1.blob.core.windows.net/ingestion/26920f66-b592-4439-9a9d-fb0f014902ec?sv=2014-02-14&sr=b&sig=usAN0kNFNnYE2tGQBI%2BARQWejX1Guiz7hdFtRhyK%2Bog%3D&se=2016-06-17T20:45:51Z&sp=rwl";
Microsoft.WindowsAzure.Storage.Blob.CloudBlockBlob blockBob =
    new Microsoft.WindowsAzure.Storage.Blob.CloudBlockBlob(new System.Uri(sasUrl));
await blockBob.UploadFromStreamAsync(stream);

  7. Invia il pacchetto di distribuzione eseguendo il seguente metodo. Ciò avviserà il Centro per i partner che hai terminato l'invio e che gli aggiornamenti dovrebbero ora essere applicati al tuo account.

    POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit

  8. Controlla lo stato eseguendo il metodo seguente per ottenere lo stato dell'invio del pacchetto di distribuzione.

    GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status

    Per confermare lo stato di invio, rivedere il valore dellostato nel corpo della risposta. Questo valore dovrebbe cambiare da CommitStarted aPreProcessingse la richiesta ha esito positivo oppure a CommitFailed se ci sono errori nella richiesta. Se ci sono errori, il campo di statusDetails contiene ulteriori dettagli sull'errore.

  9. Una volta completato correttamente l'invio, questo viene inviato allo Store per l'inserimento. È possibile continuare a monitorare lo stato di avanzamento dell'invio utilizzando il metodo precedente o visitando il Centro per i partner.

Esempi di codice

I seguenti articoli forniscono esempi di codice dettagliati che dimostrano come creare un invio di un pacchetto di distribuzione in diversi linguaggi di programmazione:

Modulo StoreBroker PowerShell

In alternativa alla chiamata diretta all'API di invio di Microsoft Store, forniamo anche un modulo PowerShell open source che implementa un'interfaccia della riga di comando sopra l'API. Questo modulo è chiamato StoreBroker. Puoi utilizzare questo modulo per gestire gli invii di app, voli e componenti aggiuntivi dalla riga di comando invece di chiamare direttamente l'API di invio di Microsoft Store oppure puoi semplicemente esplorare l'origine per visualizzare altri esempi su come chiamare questa API. Il modulo StoreBroker viene utilizzato attivamente in Microsoft come modalità principale con cui molte applicazioni di prima parte vengono inviate allo Store.

Per maggiori informazioni, vedere la nostra pagina StoreBroker su GitHub.

Gestire un'implementazione graduale del pacchetto per l'invio di un pacchetto in anteprima

Puoi implementare gradualmente i pacchetti aggiornati nell'invio di un pacchetto di distribuzione a una percentuale di clienti della tua app su Windows 10 e Windows 11. Ciò ti consente di monitorare feedback e dati analitici per i pacchetti specifici per assicurarti di essere sicuro dell'aggiornamento prima di distribuirlo su un piano più ampio. Puoi modificare la percentuale di implementazione (o interrompere l'aggiornamento) per un invio pubblicato senza dover creare un nuovo invio. Per altri dettagli, incluse le istruzioni su come abilitare e gestire l'implementazione graduale del pacchetto nel Centro per i partner, vedere questo articolo.

Per abilitare a livello di codice un'implementazione graduale del pacchetto per l'invio di un pacchetto di distribuzione, segui questo processo utilizzando i metodi nell'API di invio di Microsoft Store:

  1. Crea l'invio di un pacchetto di distribuzione or ottieni l'invio di un pacchetto di distribuzione.
  2. Nei dati di risposta, individuare la risorsapackageRollout, impostare il campotisPackageRollousu vero, e impostare il campopackageRolloutPercentage relativo alla percentuale di clienti della tua app che dovrebbero ricevere i pacchetti aggiornati.
  3. Passa i dati aggiornati di invio del pacchetto di distribuzione al metodo di aggiornamento dell'invio del pacchetto di distribuzione.

Dopo aver abilitato l'implementazione graduale del pacchetto per l'invio di un pacchetto di distribuzione, è possibile utilizzare i seguenti metodi per ottenere, aggiornare, interrompere o finalizzare l'implementazione graduale a livello di codice.

Method URI Descrizione
GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/packagerollout Ottieni le informazioni sull'implementazione graduale per l'invio di un pacchetto di distribuzione
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/updatepackagerolloutpercentage AggiornaOttieni le informazioni sull'implementazione graduale percentuale per l'invio di un pacchetto di distribuzione
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/haltpackagerollout Interrompi le informazioni sull'implementazione graduale per l'invio di un pacchetto di distribuzione
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/finalizepackagerollout Finalizza le informazioni sull'implementazione graduale per l'invio di un pacchetto di distribuzione

Risorse dati

I metodi API di invio di Microsoft Store per la gestione degli invii del pacchetto di distribuzione utilizzano le seguenti risorse di dati JSON.

Risorsa di invio distribuzione

Questa risorsa descrive un invio di pacchetto di distribuzione.

{
  "id": "1152921504621243649",
  "flightId": "cd2e368a-0da5-4026-9f34-0e7934bc6f23",
  "status": "PendingCommit",
  "statusDetails": {
    "errors": [],
    "warnings": [],
    "certificationReports": []
  },
  "flightPackages": [
    {
      "fileName": "newPackage.appx",
      "fileStatus": "PendingUpload",
      "id": "",
      "version": "1.0.0.0",
      "languages": ["en-us"],
      "capabilities": [],
      "minimumDirectXVersion": "None",
      "minimumSystemRam": "None"
    }
  ],
  "packageDeliveryOptions": {
    "packageRollout": {
        "isPackageRollout": false,
        "packageRolloutPercentage": 0.0,
        "packageRolloutStatus": "PackageRolloutNotStarted",
        "fallbackSubmissionId": "0"
    },
    "isMandatoryUpdate": false,
    "mandatoryUpdateEffectiveDate": "1601-01-01T00:00:00.0000000Z"
  },
  "fileUploadUrl": "https://productingestionbin1.blob.core.windows.net/ingestion/8b389577-5d5e-4cbe-a744-1ff2e97a9eb8?sv=2014-02-14&sr=b&sig=wgMCQPjPDkuuxNLkeG35rfHaMToebCxBNMPw7WABdXU%3D&se=2016-06-17T21:29:44Z&sp=rwl",
  "targetPublishMode": "Immediate",
  "targetPublishDate": "",
  "notesForCertification": "No special steps are required for certification of this app."
}

Questa risorsa ha i seguenti valori.

Valore Tipo Descrizione
id string L'ID per l'invio.
flightId string L'ID del pacchetto in anteprima a cui è associato l'invio.
stato string Lo stato dell'invio. Questo può essere uno dei seguenti valori:
  • None
  • Annullati
  • PendingCommit
  • CommitStarted
  • CommitFailed
  • PendingPublication
  • Pubblicazione
  • Pubblicazione completata
  • PublishFailed
  • PreProcessing
  • PreProcessingFailed
  • Certificazione
  • CertificationFailed
  • Versione
  • ReleaseFailed
statusDetails oggetto Una risorsa di dettagli sullo stato che contiene dettagli aggiuntivi sullo stato dell'invio, incluse informazioni su eventuali errori.
flightPackages array Contiene risorse del pacchetto di distribuzione che forniscono dettagli su ciascun pacchetto nell'invio.
packageDeliveryOptions oggetto Una risorsa relativa alle opzioni di consegna del pacchetto che contiene l'implementazione graduale del pacchetto e le impostazioni di aggiornamento obbligatorie per l'invio.
fileUploadUrl string L'URI della firma di accesso condiviso (SAS) per caricare eventuali pacchetti per l'invio. Se stai aggiungendo nuovi pacchetti per l'invio, carica l'archivio ZIP che contiene i pacchetti su questo URI. Per maggiori informazioni, vedere Crea invio pacchetto di distribuzione.
targetPublishMode string La modalità di pubblicazione per l'invio. Questo può essere uno dei seguenti valori:
  • Immediate
  • Manuale
  • SpecificDate
targetPublishDate string La data di pubblicazione per la presentazione in formato ISO 8601, se targetPublishMode è impostata su SpecificDate.
notesForCertification string Fornisce informazioni aggiuntive per i tester della certificazione, come le credenziali dell'account di prova e i passaggi per accedere e verificare le funzionalità. Per maggiori informazioni, vedere Note per la certificazione.

Risorsa dei dettagli sullo stato

Questa risorsa contiene dettagli aggiuntivi sullo stato di un invio. Questa risorsa ha i seguenti valori.

Valore Tipo Descrizione
errori oggetto Un array di risorse per i dettagli sullo stato che contiene dettagli sull'errore per l'invio.
avvisi oggetto Un array di risorse per i dettagli sullo stato che contiene dettagli di avviso per l'invio.
certificationReports oggetto Un array di risorse del rapporto di certificazione che fornisce l'accesso ai dati del rapporto di certificazione per l'invio. È possibile esaminare questi report per ulteriori informazioni se la certificazione fallisce.

Risorsa dei dettagli sullo stato

Questa risorsa contiene informazioni aggiuntive su eventuali errori o avvisi correlati per un invio. Questa risorsa ha i seguenti valori.

Valore Tipo Descrizione
codice string Un codice di stato dell'invio che descrive il tipo di errore o avviso..
dettagli string Un messaggio con maggiori dettagli sul problema.

Risorsa del rapporto di certificazione

Questa risorsa fornisce l'accesso ai dati del report di certificazione per un invio. Questa risorsa ha i seguenti valori.

Valore Tipo Descrizione
data string La data e l'ora in cui è stato generato il report, in formato ISO 8601.
reportUrl string L'URL da cui è possibile accedere al report.

Risorsa di distribuzione del pacchetto

Questa risorsa fornisce i dettagli sull'invio del pacchetto.

{
  "flightPackages": [
    {
      "fileName": "newPackage.appx",
      "fileStatus": "PendingUpload",
      "id": "",
      "version": "1.0.0.0",
      "languages": ["en-us"],
      "capabilities": [],
      "minimumDirectXVersion": "None",
      "minimumSystemRam": "None"
    }
  ],
}

Questa risorsa ha i seguenti valori.

Nota

Quando chiami il metodoaggiornamento di un pacchetto di distribuzione e invio, solo il fileName, fileStatus, minimumDirectXVersion, e il valore minimumSystemRam di questo oggetto sono obbligatori nel corpo della richiesta. Gli altri valori vengono popolati dal Centro per i partner.

Valore Tipo Descrizione
fileName string Il nome del pacchetto.
fileStatus string Lo stato del pacchetto. Questo può essere uno dei seguenti valori:
  • None
  • PendingUpload
  • Caricato
  • PendingDelete
id string Un ID che identifica in modo univoco il pacchetto. Questo valore viene utilizzato dal Centro per i partner.
versione string La versione del pacchetto dell'app. Per maggiori informazioni, vedere Numerazione della versione del pacchetto.
architecture string L'architettura del pacchetto app (ad esempio, ARM).
lingue array Una serie di codici lingua per le lingue supportate dall'app. Per ulteriori informazioni, vedere per ulteriori informazioniLingue supportate.
capabilities array Una serie di funzionalità richieste dal pacchetto. Per ulteriori informazioni sulle funzionalità, vedere Dichiarazione di capacità dell'app.
minimumDirectXVersion string La versione minima di DirectX supportata dal pacchetto dell'app. Questo può essere impostato solo per le app destinate a Windows 8.x; viene ignorato per le app destinate ad altre versioni. Questo può essere uno dei seguenti valori:
  • None
  • DirectX93
  • DirectX100
minimumSystemRam string La RAM minima richiesta dal pacchetto dell'app. Questo può essere impostato solo per le app destinate a Windows 8.x; viene ignorato per le app destinate ad altre versioni. Questo può essere uno dei seguenti valori:
  • None
  • Memory2GB

Risorsa relativa alle opzioni di consegna del pacco

Questa risorsa relativa alle opzioni di consegna del pacchetto contiene l'implementazione graduale del pacchetto e le impostazioni di aggiornamento obbligatorie per l'invio.

{
  "packageDeliveryOptions": {
    "packageRollout": {
        "isPackageRollout": false,
        "packageRolloutPercentage": 0.0,
        "packageRolloutStatus": "PackageRolloutNotStarted",
        "fallbackSubmissionId": "0"
    },
    "isMandatoryUpdate": false,
    "mandatoryUpdateEffectiveDate": "1601-01-01T00:00:00.0000000Z"
  },
}

Questa risorsa ha i seguenti valori.

Valore Tipo Descrizione
packageRollout oggetto Unarisorsa di distribuzione del pacchettocontiene l'implementazione graduale del pacchetto e le impostazioni di aggiornamento obbligatorie per l'invio.
isMandatoryUpdate boolean Indica se desideri considerare i pacchetti in questo invio come obbligatori per gli aggiornamenti delle app autoinstallanti. Per ulteriori informazioni sui pacchetti obbligatori per gli aggiornamenti delle app autoinstallanti, vedere Scarica e installa gli aggiornamenti del pacchetto per la tua app.
mandatoryUpdateEffectiveDate data La data e l'ora in cui i pacchetti in questo invio diventano obbligatori, nel formato ISO 8601 e nel fuso orario UTC.

Risorsa di distribuzione del pacchetto

Questa risorsa contiene le impostazioni di implementazione graduale del pacchetto per l'invio. per l'invio. Questa risorsa ha i seguenti valori.

Valore Tipo Descrizione
isPackageRollout boolean Indica se per l'invio è abilitata l'implementazione graduale del pacchetto.
packageRolloutPercentage float La percentuale di utenti che riceveranno i pacchetti nell'implementazione graduale.
packageRolloutStatus string Una delle seguenti stringhe che indica lo stato dell'implementazione graduale del pacchetto:
  • PackageRolloutNotStarted
  • PackageRolloutInProgress
  • PackageRolloutComplete
  • PackageRolloutStopped
fallbackSubmissionId string L'ID dell'invio che verrà ricevuto dai clienti che non ricevono i pacchetti di implementazione graduale.

Nota

I valori packageRolloutStatus e fallbackSubmissionId vengono assegnati dal Centro per i partner e non sono destinati a essere impostati dallo sviluppatore. Se includi questi valori nel corpo di una richiesta, questi valori verranno ignorati.

Enumerazioni

Questi metodi utilizzano le seguenti enumerazioni.

Codice di stato dell'invio

I seguenti codici rappresentano lo stato di un invio.

Codice Descrizione
Nessuna Non è stato specificato alcun codice.
InvalidArchive L'archivio ZIP contenente il pacchetto non è valido o ha un formato di archivio non riconosciuto.
MissingFiles L'archivio ZIP non contiene tutti i file elencati nei dati di invio oppure si trovano nella posizione sbagliata nell'archivio.
PackageValidationFailed La convalida di uno o più pacchetti inviati non è riuscita.
InvalidParameterValue Uno dei parametri nel corpo della richiesta non è valido.
InvalidOperation L'operazione che hai tentato non è valida.
InvalidState L'operazione tentata non è valida per lo stato attuale del pacchetto.
ResourceNotFound Impossibile trovare il pacchetto specificato.
ServiceError Un errore interno del servizio ha impedito la riuscita della richiesta. Riprova la richiesta.
ListingOptOutWarning Lo sviluppatore ha rimosso un elenco da un invio precedente o non ha incluso le informazioni sull'elenco supportate dal pacchetto.
ListingOptInWarning Lo sviluppatore ha aggiunto un elenco.
UpdateOnlyWarning Lo sviluppatore sta tentando di inserire qualcosa che abbia solo il supporto per gli aggiornamenti.
Altro L'invio è in uno stato non riconosciuto o senza categoria.
PackageValidationWarning Il processo di convalida del pacchetto ha generato un avviso.