Mengelola pengiriman penerbangan paket
API pengiriman Microsoft Store menyediakan metode yang dapat Anda gunakan untuk mengelola pengiriman penerbangan paket untuk aplikasi Anda, termasuk peluncuran paket bertahap. Untuk pengenalan API pengiriman Microsoft Store, termasuk prasyarat untuk menggunakan API, lihat Membuat dan mengelola pengiriman menggunakan layanan Microsoft Store.
Penting
Jika Anda menggunakan API pengiriman Microsoft Store untuk membuat pengiriman untuk penerbangan paket, pastikan untuk membuat perubahan lebih lanjut pada pengiriman hanya dengan menggunakan API, bukan Pusat Mitra. Jika Anda menggunakan dasbor untuk mengubah pengiriman yang awalnya Anda buat dengan menggunakan API, Anda tidak akan dapat lagi mengubah atau menerapkan pengiriman tersebut dengan menggunakan API. Dalam beberapa kasus, pengiriman dapat dibiarkan dalam status kesalahan di mana pengiriman tidak dapat dilanjutkan dalam proses pengiriman. Jika ini terjadi, Anda harus menghapus pengiriman dan membuat pengiriman baru.
Metode untuk mengelola pengiriman penerbangan paket
Gunakan metode berikut untuk mendapatkan, membuat, memperbarui, menerapkan, atau menghapus pengiriman penerbangan paket. Sebelum Anda dapat menggunakan metode ini, penerbangan paket harus sudah ada di Pusat Mitra. Anda dapat membuat penerbangan paket di Pusat Mitra atau dengan menggunakan metode API pengiriman Microsoft Store dalam yang dijelaskan dalam Mengelola penerbangan paket.
| Metode | URI | Deskripsi |
|---|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} | Dapatkan pengajuan penerbangan paket yang ada |
| GET | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status | Mendapatkan status pengiriman penerbangan paket yang ada |
| POST | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions | Membuat pengiriman penerbangan paket baru |
| PUT | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} | Memperbarui pengiriman penerbangan paket yang ada |
| POST | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit | Menerapkan pengiriman penerbangan paket baru atau yang diperbarui |
| DELETE | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} | Menghapus pengiriman penerbangan paket |
Membuat pengiriman penerbangan paket
Untuk membuat pengiriman untuk penerbangan paket, ikuti proses ini.
Jika Anda belum melakukannya, selesaikan prasyarat yang dijelaskan dalam Membuat dan mengelola pengiriman menggunakan layanan Microsoft Store, termasuk mengaitkan aplikasi Azure AD dengan akun Pusat Mitra Anda dan mendapatkan ID dan kunci klien Anda. Anda hanya perlu melakukan ini satu kali; setelah Anda memiliki ID dan kunci klien, Anda dapat menggunakannya kembali kapan saja Anda perlu membuat token akses Azure AD baru.
Dapatkan token akses Azure AD. Anda harus meneruskan token akses ini ke metode di API pengiriman Microsoft Store. Setelah mendapatkan token akses, Anda memiliki waktu 60 menit untuk menggunakannya sebelum masa berlakunya habis. Setelah token kedaluwarsa, Anda dapat memperoleh yang baru.
Buat pengiriman penerbangan paket dengan menjalankan metode berikut di API pengiriman Microsoft Store. Metode ini membuat pengiriman baru yang sedang berlangsung, yang merupakan salinan pengiriman terakhir Anda yang diterbitkan.
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissionsIsi respons berisi sumber daya pengiriman penerbangan yang mencakup ID pengiriman baru, URI tanda tangan akses bersama (SAS) untuk mengunggah paket apa pun untuk pengiriman ke Azure Blob Storage, dan data untuk pengiriman baru (termasuk semua daftar dan informasi harga).
Catatan
SAS URI menyediakan akses ke sumber daya yang aman di penyimpanan Azure tanpa memerlukan kunci akun. Untuk informasi latar belakang tentang URI SAS dan penggunaannya dengan Azure Blob Storage, lihat Tanda Tangan Akses Bersama, Bagian 1: Memahami model SAS dan Tanda Tangan Akses Bersama, Bagian 2: Membuat dan menggunakan SAS dengan penyimpanan Blob.
Jika Anda menambahkan paket baru untuk pengiriman, siapkan paket dan tambahkan ke arsip ZIP.
Revisi data pengiriman penerbangan dengan perubahan yang diperlukan untuk pengiriman baru, dan jalankan metode berikut untuk memperbarui pengiriman penerbangan paket.
PUT https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}Catatan
Jika Anda menambahkan paket baru untuk pengiriman, pastikan Anda memperbarui data pengiriman untuk merujuk ke nama dan jalur relatif file-file ini di arsip ZIP.
Jika Anda menambahkan paket baru untuk pengiriman, unggah arsip ZIP ke Azure Blob Storage menggunakan URI SAS yang disediakan dalam isi respons metode POST yang Anda panggil sebelumnya. Ada berbagai pustaka Azure yang dapat Anda gunakan untuk melakukan ini di berbagai platform, termasuk:
- Pustaka Klien Azure Storage untuk .NET
- Penyimpanan Azure SDK untuk PHP
- Azure Storage SDK untuk Python
Contoh kode C# berikut menunjukkan cara mengunggah arsip ZIP ke Azure Blob Storage menggunakan kelas CloudBlockBlob di Pustaka Klien Azure Storage untuk .NET. Contoh ini mengasumsikan bahwa arsip ZIP telah ditulis ke objek stream.
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);Terapkan pengiriman penerbangan paket dengan menjalankan metode berikut. Ini akan memperingatkan Pusat Mitra bahwa Anda selesai dengan pengiriman Anda dan bahwa pembaruan Anda sekarang harus diterapkan ke akun Anda.
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commitPeriksa status penerapan dengan menjalankan metode berikut untuk mendapatkan status pengiriman penerbangan paket.
GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/statusUntuk mengonfirmasi status pengiriman, tinjau nilai status di isi respons. Nilai ini harus berubah dari CommitStarted menjadi PreProcessing jika permintaan berhasil atau ke CommitFailed jika ada kesalahan dalam permintaan. Jika ada kesalahan, bidang statusDetails berisi detail lebih lanjut tentang kesalahan tersebut.
Setelah penerapan berhasil diselesaikan, pengiriman dikirim ke Toko untuk diserap. Anda dapat terus memantau kemajuan pengiriman dengan menggunakan metode sebelumnya, atau dengan mengunjungi Pusat Mitra.
Contoh kode
Artikel berikut ini menyediakan contoh kode terperinci yang menunjukkan cara membuat pengiriman penerbangan paket dalam beberapa bahasa pemrograman yang berbeda:
Modul StoreBroker PowerShell
Sebagai alternatif untuk memanggil API pengiriman Microsoft Store secara langsung, kami juga menyediakan modul PowerShell sumber terbuka yang mengimplementasikan antarmuka baris perintah di atas API. Modul ini disebut StoreBroker. Anda dapat menggunakan modul ini untuk mengelola pengiriman aplikasi, penerbangan, dan add-on dari baris perintah alih-alih memanggil API pengiriman Microsoft Store secara langsung, atau Anda cukup menelusuri sumber untuk melihat lebih banyak contoh tentang cara memanggil API ini. Modul StoreBroker secara aktif digunakan dalam Microsoft sebagai cara utama bahwa banyak aplikasi pihak pertama dikirimkan ke Store.
Untuk informasi selengkapnya, lihat halaman StoreBroker kami di GitHub.
Mengelola peluncuran paket bertahap untuk pengiriman paket penerbangan
Anda dapat meluncurkan paket yang diperbarui secara bertahap dalam pengiriman penerbangan paket ke persentase pelanggan aplikasi Anda di Windows 10 dan Windows 11. Ini memungkinkan Anda memantau umpan balik dan data analitik untuk paket tertentu untuk memastikan Anda yakin tentang pembaruan sebelum meluncurkannya secara lebih luas. Anda dapat mengubah persentase peluncuran (atau menghentikan pembaruan) untuk pengiriman yang diterbitkan tanpa harus membuat pengiriman baru. Untuk detail selengkapnya, termasuk instruksi tentang cara mengaktifkan dan mengelola peluncuran paket bertahap di Pusat Mitra, lihat artikel ini.
Untuk mengaktifkan peluncuran paket bertahap secara terprogram untuk pengiriman penerbangan paket, ikuti proses ini menggunakan metode di API pengiriman Microsoft Store:
- Buat pengiriman paket penerbangan atau dapatkan pengiriman paket penerbangan.
- Dalam data respons, temukan sumber daya packageRollout , atur bidang isPackageRollout ke true, dan atur bidang packageRolloutPercentage ke persentase pelanggan aplikasi Anda yang harus mendapatkan paket yang diperbarui.
- Teruskan data pengiriman penerbangan paket yang diperbarui ke metode pengiriman penerbangan paket.
Setelah peluncuran paket bertahap diaktifkan untuk pengiriman penerbangan paket, Anda dapat menggunakan metode berikut untuk mendapatkan, memperbarui, menghentikan, atau menyelesaikan peluncuran bertahap secara terprogram.
| Metode | URI | Deskripsi |
|---|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/packagerollout | Dapatkan info peluncuran bertahap untuk pengiriman penerbangan paket |
| POST | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/updatepackagerolloutpercentage | Memperbarui persentase peluncuran bertahap untuk pengiriman penerbangan paket |
| POST | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/haltpackagerollout | Menghentikan peluncuran bertahap untuk pengiriman penerbangan paket |
| POST | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/finalizepackagerollout | Menyelesaikan peluncuran bertahap untuk pengiriman penerbangan paket |
Sumber daya data
Metode API pengiriman Microsoft Store untuk mengelola pengiriman penerbangan paket menggunakan sumber daya data JSON berikut.
Sumber daya pengiriman penerbangan
Sumber daya ini menjelaskan pengiriman penerbangan paket.
{
"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."
}
Sumber daya ini memiliki nilai berikut.
| Nilai | Jenis | Deskripsi |
|---|---|---|
| id | string | ID untuk pengiriman. |
| flightId | string | ID penerbangan paket yang dikaitkan dengan pengiriman. |
| status | string | Status pengiriman. Ini bisa menjadi salah satu nilai berikut:
|
| statusDetails | objek | Sumber daya detail status yang berisi detail tambahan tentang status pengiriman, termasuk informasi tentang kesalahan apa pun. |
| flightPackages | array | Berisi sumber daya paket penerbangan yang memberikan detail tentang setiap paket dalam pengiriman. |
| packageDeliveryOptions | objek | Sumber daya opsi pengiriman paket yang berisi peluncuran paket bertahap dan pengaturan pembaruan wajib untuk pengiriman. |
| fileUploadUrl | string | URI tanda tangan akses bersama (SAS) untuk mengunggah paket apa pun untuk pengiriman. Jika Anda menambahkan paket baru untuk pengiriman, unggah arsip ZIP yang berisi paket ke URI ini. Untuk informasi selengkapnya, lihat Membuat pengiriman penerbangan paket. |
| targetPublishMode | string | Mode penerbitan untuk pengiriman. Ini bisa menjadi salah satu nilai berikut:
|
| targetPublishDate | string | Tanggal penerbitan untuk pengiriman dalam format ISO 8601, jika targetPublishMode diatur ke SpecificDate. |
| notesForCertification | string | Memberikan info tambahan untuk penguji sertifikasi, seperti info masuk akun pengujian dan langkah-langkah untuk mengakses dan memverifikasi fitur. Untuk informasi selengkapnya, lihat Catatan untuk sertifikasi. |
Sumber daya detail status
Sumber daya ini berisi detail tambahan tentang status pengiriman. Sumber daya ini memiliki nilai berikut.
| Nilai | Jenis | Deskripsi |
|---|---|---|
| errors | objek | Array sumber daya detail status yang berisi detail kesalahan untuk pengiriman. |
| Peringatan | objek | Array sumber daya detail status yang berisi detail peringatan untuk pengiriman. |
| certificationReports | objek | Array sumber daya laporan sertifikasi yang menyediakan akses ke data laporan sertifikasi untuk pengiriman. Anda dapat memeriksa laporan ini untuk informasi lebih lanjut jika sertifikasi gagal. |
Sumber daya detail status
Sumber daya ini berisi informasi tambahan tentang kesalahan atau peringatan terkait untuk pengiriman. Sumber daya ini memiliki nilai berikut.
| Nilai | Jenis | Deskripsi |
|---|---|---|
| kode | string | Kode status pengiriman yang menjelaskan jenis kesalahan atau peringatan. |
| detail | string | Pesan dengan detail selengkapnya tentang masalah ini. |
Sumber daya laporan sertifikasi
Sumber daya ini menyediakan akses ke data laporan sertifikasi untuk pengiriman. Sumber daya ini memiliki nilai berikut.
| Nilai | Jenis | Deskripsi |
|---|---|---|
| tanggal | string | Tanggal dan waktu laporan dibuat, dalam format ISO 8601. |
| reportUrl | string | URL tempat Anda dapat mengakses laporan. |
Sumber daya paket penerbangan
Sumber daya ini menyediakan detail tentang paket dalam pengiriman.
{
"flightPackages": [
{
"fileName": "newPackage.appx",
"fileStatus": "PendingUpload",
"id": "",
"version": "1.0.0.0",
"languages": ["en-us"],
"capabilities": [],
"minimumDirectXVersion": "None",
"minimumSystemRam": "None"
}
],
}
Sumber daya ini memiliki nilai berikut.
Catatan
Saat memanggil pembaruan metode pengiriman penerbangan paket , hanya nilai fileName, fileStatus, minimumDirectXVersion, dan minimumSystemRam objek ini yang diperlukan dalam isi permintaan. Nilai lainnya diisi oleh Pusat Mitra.
| Nilai | Jenis | Deskripsi |
|---|---|---|
| fileName | string | Nama paket. |
| fileStatus | string | Status paket. Ini bisa menjadi salah satu nilai berikut:
|
| id | string | ID yang secara unik mengidentifikasi paket. Nilai ini digunakan oleh Pusat Mitra. |
| versi | string | Versi paket aplikasi. Untuk informasi selengkapnya, lihat Penomoran versi paket. |
| Arsitektur | string | Arsitektur paket aplikasi (misalnya, ARM). |
| languages | array | Array kode bahasa untuk bahasa yang didukung aplikasi. Untuk informasi selengkapnya, lihat Untuk informasi selengkapnya, lihat Bahasa yang didukung. |
| capabilities | array | Array kemampuan yang diperlukan oleh paket. Untuk informasi selengkapnya tentang kemampuan, lihat Deklarasi kemampuan aplikasi. |
| minimumDirectXVersion | string | Versi DirectX minimum yang didukung oleh paket aplikasi. Ini hanya dapat diatur untuk aplikasi yang menargetkan Windows 8.x; ini diabaikan untuk aplikasi yang menargetkan versi lain. Ini bisa menjadi salah satu nilai berikut:
|
| minimumSystemRam | string | RAM minimum yang diperlukan oleh paket aplikasi. Ini hanya dapat diatur untuk aplikasi yang menargetkan Windows 8.x; ini diabaikan untuk aplikasi yang menargetkan versi lain. Ini bisa menjadi salah satu nilai berikut:
|
Sumber daya opsi pengiriman paket
Sumber daya ini berisi peluncuran paket bertahap dan pengaturan pembaruan wajib untuk pengiriman.
{
"packageDeliveryOptions": {
"packageRollout": {
"isPackageRollout": false,
"packageRolloutPercentage": 0.0,
"packageRolloutStatus": "PackageRolloutNotStarted",
"fallbackSubmissionId": "0"
},
"isMandatoryUpdate": false,
"mandatoryUpdateEffectiveDate": "1601-01-01T00:00:00.0000000Z"
},
}
Sumber daya ini memiliki nilai berikut.
| Nilai | Jenis | Deskripsi |
|---|---|---|
| packageRollout | objek | Sumber daya peluncuran paket yang berisi pengaturan peluncuran paket bertahap untuk pengiriman. |
| isMandatoryUpdate | boolean | Menunjukkan apakah Anda ingin memperlakukan paket dalam pengiriman ini sebagai wajib untuk menginstal pembaruan aplikasi sendiri. Untuk informasi selengkapnya tentang paket wajib untuk menginstal pembaruan aplikasi sendiri, lihat Mengunduh dan menginstal pembaruan paket untuk aplikasi Anda. |
| mandatoryUpdateEffectiveDate | tanggal | Tanggal dan waktu ketika paket dalam pengiriman ini menjadi wajib, dalam format ISO 8601 dan zona waktu UTC. |
Sumber daya peluncuran paket
Sumber daya ini berisi pengaturan peluncuran paket bertahap untuk pengiriman. Sumber daya ini memiliki nilai berikut.
| Nilai | Jenis | Deskripsi |
|---|---|---|
| isPackageRollout | boolean | Menunjukkan apakah peluncuran paket bertahap diaktifkan untuk pengiriman. |
| packageRolloutPercentage | float | Persentase pengguna yang akan menerima paket dalam peluncuran bertahap. |
| packageRolloutStatus | string | Salah satu string berikut yang menunjukkan status peluncuran paket bertahap:
|
| fallbackSubmissionId | string | ID pengiriman yang akan diterima oleh pelanggan yang tidak mendapatkan paket peluncuran bertahap. |
Catatan
Nilai packageRolloutStatus dan fallbackSubmissionId ditetapkan oleh Pusat Mitra, dan tidak dimaksudkan untuk ditetapkan oleh pengembang. Jika Anda menyertakan nilai-nilai ini dalam isi permintaan, nilai-nilai ini akan diabaikan.
Enum
Metode ini menggunakan enum berikut.
Kode status pengiriman
Kode berikut menunjukkan status pengiriman.
| Kode | Deskripsi |
|---|---|
| Tidak ada | Tidak ada kode yang ditentukan. |
| InvalidArchive | Arsip ZIP yang berisi paket tidak valid atau memiliki format arsip yang tidak dikenal. |
| MissingFiles | Arsip ZIP tidak memiliki semua file yang tercantum dalam data pengiriman Anda, atau berada di lokasi yang salah dalam arsip. |
| PackageValidationFailed | Satu atau beberapa paket dalam pengiriman Anda gagal divalidasi. |
| InvalidParameterValue | Salah satu parameter dalam isi permintaan tidak valid. |
| InvalidOperation | Operasi yang Anda coba tidak valid. |
| InvalidState | Operasi yang Anda coba tidak valid untuk status penerbangan paket saat ini. |
| ResourceNotFound | Penerbangan paket yang ditentukan tidak dapat ditemukan. |
| ServiceError | Kesalahan layanan internal mencegah permintaan berhasil. Coba permintaan lagi. |
| ListingOptOutWarning | Pengembang menghapus daftar dari pengiriman sebelumnya, atau tidak menyertakan informasi daftar yang didukung oleh paket. |
| ListingOptInWarning | Pengembang menambahkan daftar. |
| UpdateOnlyWarning | Pengembang mencoba menyisipkan sesuatu yang hanya memiliki dukungan pembaruan. |
| Lainnya | Pengiriman berada dalam status tidak dikenal atau tidak dikategorikan. |
| PackageValidationWarning | Proses validasi paket menghasilkan peringatan. |
Topik terkait
- Membuat dan mengelola pengiriman menggunakan layanan Microsoft Store
- Mengelola penerbangan paket menggunakan API pengiriman Microsoft Store
- Mendapatkan pengiriman paket penerbangan
- Membuat pengiriman penerbangan paket
- Memperbarui pengiriman penerbangan paket
- Menerapkan pengiriman penerbangan paket
- Menghapus pengiriman penerbangan paket
- Mendapatkan status pengiriman penerbangan paket
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk