Mengelola pengiriman add-on

  • Artikel

API pengiriman Microsoft Store menyediakan metode yang dapat Anda gunakan untuk mengelola pengiriman add-on (juga dikenal sebagai produk dalam aplikasi atau IAP) untuk aplikasi Anda. 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 add-on, pastikan untuk membuat perubahan lebih lanjut pada pengiriman hanya dengan menggunakan API, daripada membuat perubahan di Pusat Mitra. Jika Anda menggunakan Pusat Mitra 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. Jika ini terjadi, Anda harus menghapus pengiriman dan membuat pengiriman baru.

Metode untuk mengelola pengiriman add-on

Gunakan metode berikut untuk mendapatkan, membuat, memperbarui, menerapkan, atau menghapus pengiriman add-on. Sebelum Anda dapat menggunakan metode ini, add-on harus sudah ada di akun Pusat Mitra Anda. Anda dapat membuat add-on di Pusat Mitra dengan menentukan jenis produk dan ID produknya atau dengan menggunakan metode API pengiriman Microsoft Store dalam dijelaskan dalam Mengelola add-on.

Metode URI Deskripsi
GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Mendapatkan pengiriman add-on yang sudah ada
GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/status Mendapatkan status pengiriman add-on yang sudah ada
POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions Membuat pengiriman add-on baru
TARUH https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Memperbarui pengiriman add-on yang sudah ada
POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/commit Menerapkan pengiriman add-on baru atau yang diperbarui
DELETE https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Menghapus pengiriman add-on

Membuat pengiriman add-on

Untuk membuat pengiriman add-on, ikuti proses ini.

  1. Jika Anda belum melakukannya, selesaikan prasyarat yang dijelaskan dalam Membuat dan mengelola pengiriman menggunakan layanan Microsoft Store, termasuk mengaitkan aplikasi Microsoft Azure ACTIVE Directory 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 Microsoft Azure AD baru.

  2. Dapatkan token akses Azure ACTIVE Directory. Anda harus meneruskan token akses ini ke metode di API pengiriman Microsoft Store. Setelah mendapatkan token akses, Anda memiliki waktu 60 menit untuk menggunakan token akses sebelum masa berlakunya habis. Setelah token kedaluwarsa, Anda dapat memperoleh yang baru.

  3. Jalankan metode berikut di API pengiriman Microsoft Store. Metode ini membuat pengiriman baru yang sedang berlangsung, yang merupakan salinan pengiriman terakhir Anda yang diterbitkan. Untuk informasi selengkapnya, lihat Membuat pengiriman add-on.

    POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions

    Isi respons berisi sumber daya pengiriman add-on yang menyertakan ID pengiriman baru, URI tanda tangan akses bersama (SAS) untuk mengunggah ikon add-on apa pun untuk pengiriman ke Azure Blob Storage, dan semua data untuk pengiriman baru (seperti daftar dan informasi harga).

    Catatan

    SAS URI menyediakan akses ke sumber daya 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.

  4. Jika Anda menambahkan ikon baru untuk pengiriman, siapkan ikon dan tambahkan ke arsip ZIP.

  5. Perbarui data pengiriman add-on dengan perubahan yang diperlukan untuk pengiriman baru, dan jalankan metode berikut untuk memperbarui pengiriman. Untuk informasi selengkapnya, lihat Memperbarui pengiriman add-on.

    PUT https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}

    Catatan

    Jika Anda menambahkan ikon baru untuk pengiriman, pastikan Anda memperbarui data pengiriman untuk merujuk ke nama dan jalur relatif file-file ini di arsip ZIP.

  6. Jika Anda menambahkan ikon 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:

    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);

  7. Terapkan pengiriman 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. Untuk informasi selengkapnya, lihat Menerapkan pengiriman add-on.

    POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/commit

  8. Periksa status penerapan dengan menjalankan metode berikut. Untuk informasi selengkapnya, lihat Mendapatkan status pengiriman add-on.

    GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/status

    Untuk mengonfirmasi status pengiriman, tinjau nilai status dalam 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.

  9. Setelah penerapan berhasil diselesaikan, pengiriman dikirim ke Store 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 add-on 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 contoh selengkapnya 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.

Sumber daya data

Metode API pengiriman Microsoft Store untuk mengelola pengiriman add-on menggunakan sumber daya data JSON berikut.

Sumber daya pengiriman add-on

Sumber daya ini menjelaskan pengiriman add-on.

{
  "id": "1152921504621243680",
  "contentType": "EMagazine",
  "keywords": [
    "books"
  ],
  "lifetime": "FiveDays",
  "listings": {
    "en": {
      "description": "English add-on description",
      "icon": {
        "fileName": "add-on-en-us-listing2.png",
        "fileStatus": "Uploaded"
      },
      "title": "Add-on Title (English)"
    },
    "ru": {
      "description": "Russian add-on description",
      "icon": {
        "fileName": "add-on-ru-listing.png",
        "fileStatus": "Uploaded"
      },
      "title": "Add-on Title (Russian)"
    }
  },
  "pricing": {
    "marketSpecificPricings": {
      "RU": "Tier3",
      "US": "Tier4",
    },
    "sales": [],
    "priceId": "Free",
    "isAdvancedPricingModel": true
  },
  "targetPublishDate": "2016-03-15T05:10:58.047Z",
  "targetPublishMode": "Immediate",
  "tag": "SampleTag",
  "visibility": "Public",
  "status": "PendingCommit",
  "statusDetails": {
    "errors": [
      {
        "code": "None",
        "details": "string"
      }
    ],
    "warnings": [
      {
        "code": "ListingOptOutWarning",
        "details": "You have removed listing language(s): []"
      }
    ],
    "certificationReports": [
      {
      }
    ]
  },
  "fileUploadUrl": "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",
  "friendlyName": "Submission 2"
}

Sumber daya ini memiliki nilai berikut.

Value Jenis Deskripsi
id string ID pengiriman. ID ini tersedia dalam data respons untuk permintaan untuk membuat pengiriman add-on, mendapatkan semua add-on, dan mendapatkan add-on. Untuk pengiriman yang dibuat di Pusat Mitra, ID ini juga tersedia di URL untuk halaman pengiriman di Pusat Mitra.
contentType string Jenis konten yang disediakan dalam add-on. Ini bisa menjadi salah satu nilai berikut:
  • NotSet
  • BookDownload
  • EMagazine
  • ENewspaper
  • MusikUnduh
  • MusicStream
  • OnlineDataStorage
  • VideoDownload
  • VideoStream
  • Asp
  • OnlineUnduh
kata kunci array Array string yang berisi hingga 10 kata kunci untuk add-on. Aplikasi Anda dapat mengkueri add-on menggunakan kata kunci ini.
lifetime string Masa pakai add-on. Ini bisa menjadi salah satu nilai berikut:
  • Selamanya
  • OneDay
  • Tiga Hari
  • FiveDays
  • OneWeek
  • TwoWeeks
  • OneMonth
  • TwoMonths
  • ThreeMonths
  • SixMonths
  • OneYear
Daftar object Kamus pasangan kunci dan nilai, di mana setiap kunci adalah kode negara ISO 3166-1 alpha-2 dua huruf dan setiap nilai adalah sumber daya daftar yang berisi info daftar untuk add-on.
harga object Sumber daya harga yang berisi info harga untuk add-on.
targetPublishMode string Mode penerbitan untuk pengiriman. Ini bisa menjadi salah satu nilai berikut:
  • Segera
  • Manual
  • SpecificDate
targetPublishDate string Tanggal penerbitan untuk pengiriman dalam format ISO 8601, jika targetPublishMode diatur ke SpecificDate.
tag string Data pengembang kustom untuk add-on (informasi ini sebelumnya disebut tag).
Visibilitas string Visibilitas add-on. Ini bisa menjadi salah satu nilai berikut:
  • Tersembunyi
  • Publik
  • Privat
  • NotSet
status string Status pengiriman. Ini bisa menjadi salah satu nilai berikut:
  • Tidak ada
  • Dibatalkan
  • PendingCommit
  • CommitStarted
  • CommitFailed
  • PendingPublication
  • Memublikasikan
  • Diterbitkan
  • PublishFailed
  • Preprocessing
  • PreProcessingFailed
  • Sertifikasi
  • CertificationFailed
  • Lepaskan
  • ReleaseFailed
statusDetails object Sumber daya detail status yang berisi detail tambahan tentang status pengiriman, termasuk informasi tentang kesalahan apa pun.
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 add-on.
friendlyName string Nama pengiriman yang mudah diingat, seperti yang ditunjukkan di Pusat Mitra. Nilai ini dihasilkan untuk Anda saat Anda membuat pengiriman.

Mencantumkan sumber daya

Sumber daya ini berisi info daftar untuk add-on. Sumber daya ini memiliki nilai berikut.

Value Jenis Deskripsi
description string Deskripsi untuk daftar add-on.
ikon object Sumber daya ikon yang berisi data untuk ikon untuk daftar add-on.
title string Judul untuk daftar add-on.

Sumber daya ikon

Sumber daya ini berisi data ikon untuk daftar add-on. Sumber daya ini memiliki nilai berikut.

Value Jenis Deskripsi
fileName string Nama file ikon dalam arsip ZIP yang Anda unggah untuk pengiriman. Ikon harus berupa file .png yang berukuran tepat 300 x 300 piksel.
fileStatus string Status file ikon. Ini bisa menjadi salah satu nilai berikut:
  • Tidak
  • PendingUpload
  • Diunggah
  • PendingDelete

Sumber daya harga

Sumber daya ini berisi info harga untuk add-on. Sumber daya ini memiliki nilai berikut.

Value Jenis Deskripsi
marketSpecificPricings object Kamus pasangan kunci dan nilai, di mana setiap kunci adalah kode negara ISO 3166-1 alpha-2 dua huruf dan setiap nilai adalah tingkat harga. Item-item ini mewakili harga kustom untuk add-on Anda di pasar tertentu. Setiap item dalam kamus ini mengambil alih harga dasar yang ditentukan oleh nilai priceId untuk pasar yang ditentukan.
penjualan array Ditolak. Array sumber daya penjualan yang berisi informasi penjualan untuk add-on.
priceId string Tingkat harga yang menentukan harga dasar untuk add-on.
isAdvancedPricingModel Boolean Jika true, akun pengembang Anda memiliki akses ke set tingkat harga yang diperluas dari .99 USD ke 1999,99 USD. Jika false, akun pengembang Anda memiliki akses ke set tingkat harga asli dari .99 USD hingga 999,99 USD. Untuk informasi selengkapnya tentang berbagai tingkatan, lihat tingkat harga.

Catatan Bidang ini bersifat baca-saja.

Jual sumber daya

Sumber daya ini berisi info penjualan untuk add-on.

Penting

Sumber daya Penjualan tidak lagi didukung, dan saat ini Anda tidak dapat mendapatkan atau memodifikasi data penjualan untuk pengiriman add-on menggunakan API pengiriman Microsoft Store. Di masa mendatang, kami akan memperbarui API pengiriman Microsoft Store untuk memperkenalkan cara baru untuk mengakses informasi penjualan secara terprogram untuk pengiriman add-on.

  • Setelah memanggil metode GET untuk mendapatkan pengiriman add-on, nilai penjualan akan kosong. Anda dapat terus menggunakan Pusat Mitra untuk mendapatkan data penjualan untuk pengiriman add-on Anda.
  • Saat memanggil metode PUT untuk memperbarui pengiriman add-on, informasi dalam nilai penjualan diabaikan. Anda dapat terus menggunakan Pusat Mitra untuk mengubah data penjualan untuk pengiriman add-on Anda.

Sumber daya ini memiliki nilai berikut.

Value Jenis Deskripsi
nama string Nama penjualan.
basePriceId string Tingkat harga yang digunakan untuk harga dasar penjualan.
startDate string Tanggal mulai untuk penjualan dalam format ISO 8601.
endDate string Tanggal akhir untuk penjualan dalam format ISO 8601.
marketSpecificPricings object Kamus pasangan kunci dan nilai, di mana setiap kunci adalah kode negara ISO 3166-1 alpha-2 dua huruf dan setiap nilai adalah tingkat harga. Item-item ini mewakili harga kustom untuk add-on Anda di pasar tertentu. Setiap item dalam kamus ini mengambil alih harga dasar yang ditentukan oleh nilai basePriceId untuk pasar yang ditentukan.

Sumber daya detail status

Sumber daya ini berisi detail tambahan tentang status pengiriman. Sumber daya ini memiliki nilai berikut.

Value Jenis Deskripsi
errors object Array sumber daya detail status yang berisi detail kesalahan untuk pengiriman.
peringatan object Array sumber daya detail status yang berisi detail peringatan untuk pengiriman.
certificationReports object 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.

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

Value Jenis Deskripsi
date string Tanggal dan waktu laporan dibuat, dalam format ISO 8601.
reportUrl string URL tempat Anda dapat mengakses laporan.

Enum

Metode ini menggunakan enum berikut.

Tingkat harga

Nilai berikut mewakili tingkat harga yang tersedia di sumber daya sumber daya harga untuk pengiriman add-on.

Nilai Deskripsi
Base Tingkat harga tidak ditetapkan; gunakan harga dasar untuk add-on.
Tidak Tersedia Add-on tidak tersedia di wilayah yang ditentukan.
Gratis Add-on gratis.
Tingkat xxxx String yang menentukan tingkat harga untuk add-on, dalam format Tierxxxx. Saat ini, rentang tingkat harga berikut didukung:

  • Jika nilai isAdvancedPricingModel dari sumber daya harga benar, nilai tingkat harga yang tersedia untuk akun Anda adalah Tier1012 - Tier1424.
  • Jika nilai isAdvancedPricingModel dari sumber daya harga salah, nilai tingkat harga yang tersedia untuk akun Anda adalah Tier2 - Tier96.
Untuk melihat tabel lengkap tingkat harga yang tersedia untuk akun pengembang Anda, termasuk harga khusus pasar yang terkait dengan setiap tingkatan, buka halaman Harga dan ketersediaan untuk salah satu pengiriman aplikasi Anda di Pusat Mitra dan klik tautan lihat tabel di bagian Pasar dan harga kustom (untuk beberapa akun pengembang, tautan ini ada di bagian Harga ).

Kode status pengiriman

Nilai berikut mewakili kode status pengiriman.

Nilai Deskripsi
Tidak 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 dalam status tidak dikenali atau tidak dikategorikan.
PackageValidationWarning Proses validasi paket menghasilkan peringatan.