Permintaan layanan pemberitahuan push dan header respons (aplikasi Windows Runtime)

Topik ini menjelaskan API web layanan-ke-layanan dan protokol yang diperlukan untuk mengirim pemberitahuan push.

Lihat ikhtisar Windows Push Notification Services (WNS) untuk pemahaman konsep mengenai pemberitahuan push dan konsep, persyaratan, serta operasi WNS.

Meminta dan menerima token akses

Bagian ini menjelaskan parameter permintaan dan respons yang terlibat saat Anda mengautentikasi dengan WNS.

Permintaan sebuah token akses

Permintaan HTTP dikirim ke WNS untuk mengautentikasi layanan cloud dan mengambil token akses sebagai imbalannya. Permintaan dikeluarkan untuk https://login.live.com/accesstoken.srf menggunakan Secure Sockets Layer (SSL).

Parameter permintaan token akses

Layanan cloud mengirimkan parameter yang diperlukan ini dalam isi permintaan HTTP, menggunakan format "application/x-www-form-urlencoded". Anda harus memastikan bahwa semua parameter dikodekan URL.

Parameter	Required	Description
grant_type	TRUE	Harus diatur ke client_credentials.
client_id	TRUE	Pengidentifikasi keamanan paket (SID) untuk layanan awan Anda seperti yang ditetapkan saat Anda mendaftarkan aplikasi Anda dengan Microsoft Store.
client_secret	TRUE	Kunci rahasia untuk layanan awan Anda seperti yang ditetapkan saat Anda mendaftarkan aplikasi Anda dengan Microsoft Store.
cakupan	TRUE	Harus disetel ke notify.windows.com

Tanggapan token akses

WNS mengautentikasi layanan cloud dan, jika berhasil, merespons dengan "200 OK", termasuk token akses. Jika tidak, WNS merespons dengan kode kesalahan HTTP yang sesuai seperti yang dijelaskan dalam draf protokol OAuth 2.0.

Parameter respons token akses

Token akses dikembalikan dalam respons HTTP jika layanan cloud berhasil diautentikasi. Token akses ini dapat digunakan dalam permintaan pemberitahuan hingga kedaluwarsa. Respons HTTP menggunakan jenis media "application/json".

Parameter	Required	Description
access_token	TRUE	Token akses yang akan digunakan layanan cloud saat mengirim pemberitahuan.
token_type	FALSE	Selalu dikembalikan sebagai bearer.

Kode respons

Kode respons HTTP	Description
200 OK (Permintaan berhasil)	Permintaan berhasil.
400 Permintaan Tidak Valid	Autentikasi gagal. Lihat draf OAuth RFC (Request for Comments) untuk parameter respons.

Example

Berikut ini memperlihatkan contoh respons autentikasi yang berhasil:

 HTTP/1.1 200 OK   
 Cache-Control: no-store
 Content-Length: 422
 Content-Type: application/json
 
 {
     "access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=", 
     "token_type":"bearer",
     "expires_in": 86400
 }

Mengirim permintaan pemberitahuan dan menerima respons

Bagian ini menjelaskan header yang terlibat dalam permintaan HTTP ke WNS untuk mengirimkan pemberitahuan dan yang terlibat dalam balasan.

• Kirim permintaan pemberitahuan
• Mengirim respons pemberitahuan
• Fitur HTTP yang tidak didukung

Kirim permintaan pemberitahuan

Saat mengirim permintaan pemberitahuan, aplikasi panggilan membuat permintaan HTTP melalui SSL, yang ditujukan ke saluran Pengidentifikasi Sumber Daya Seragam (URI). "Content-Length" adalah header HTTP standar yang harus ditentukan dalam permintaan. Semua header standar lainnya bersifat opsional atau tidak didukung.

Selain itu, header permintaan kustom yang tercantum di sini dapat digunakan dalam permintaan pemberitahuan. Beberapa header diperlukan sementara yang lain bersifat opsional.

Parameter permintaan tersebut

Nama Header	Required	Description
Authorization	TRUE	Header otorisasi HTTP standar yang digunakan untuk mengautentikasi permintaan pemberitahuan Anda. Layanan cloud Anda menyediakan token aksesnya di header ini.
Content-Type	TRUE	Header otorisasi HTTP standar. Untuk pemberitahuan toast, tile, dan lencana, header ini harus diatur ke text/xml. Untuk pemberitahuan mentah, header ini harus diatur ke application/octet-stream.
Content-Length	TRUE	Header otorisasi HTTP standar untuk menunjukkan ukuran payload permintaan.
X-WNS-Type	TRUE	Menentukan jenis pemberitahuan dalam payload: tile, toast, lencana, atau data mentah.
X-WNS-Cache-Policy	FALSE	Mengaktifkan atau menonaktifkan caching pemberitahuan. Header ini hanya berlaku untuk ubin, lencana, dan notifikasi mentah.
X-WNS-RequestForStatus	FALSE	Meminta status perangkat dan status koneksi WNS dalam respons pemberitahuan.
X-WNS-Tag	FALSE	String yang digunakan untuk memberikan pemberitahuan dengan label identifikasi, digunakan untuk tile yang mendukung antrean pemberitahuan. Header ini hanya berlaku untuk pemberitahuan petak peta.
X-WNS-TTL	FALSE	Nilai bilangan bulat, dinyatakan dalam hitungan detik, yang menentukan waktu hidup (TTL).
MS-CV	FALSE	Nilai Vektor Korelasi yang digunakan untuk permintaan Anda.

Catatan penting

• Content-Length dan Content-Type adalah satu-satunya header HTTP standar yang disertakan dalam pemberitahuan yang dikirimkan kepada klien, terlepas dari apakah header standar lainnya disertakan dalam permintaan.
• Semua header HTTP standar lainnya diabaikan atau mengembalikan kesalahan jika fungsionalitas tidak didukung.
• Mulai Februari 2023, WNS hanya akan menyimpan satu pemberitahuan petak peta saat perangkat offline.

Authorization

Header otorisasi digunakan untuk menentukan kredensial pihak pemanggil, mengikuti metode otorisasi OAuth 2.0 untuk token pembawa .

Sintaksis terdiri dari string harfiah "Pembawa", diikuti oleh spasi, diikuti oleh token akses Anda. Token akses ini diambil dengan mengeluarkan permintaan token akses yang dijelaskan di atas. Token akses yang sama dapat digunakan pada permintaan pemberitahuan berikutnya hingga kedaluwarsa.

Header ini diperlukan.

Authorization: Bearer <access-token>

X-WNS-Type

Ini adalah jenis pemberitahuan yang didukung oleh WNS. Header ini menunjukkan jenis pemberitahuan dan bagaimana WNS harus menanganinya. Setelah pemberitahuan mencapai klien, payload aktual divalidasi terhadap jenis yang ditentukan ini. Header ini diperlukan.

X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw

Value	Description
wns/badge	Pemberitahuan untuk membuat overlay lencana pada petak peta. Header Tipe Konten yang disertakan dalam permintaan pemberitahuan harus diatur ke text/xml.
wns/tile	Pemberitahuan untuk memperbarui konten petak peta. Header Tipe Konten yang disertakan dalam permintaan pemberitahuan harus diatur ke text/xml.
wns/toast	Pemberitahuan untuk menaikkan toast pada klien. Header Tipe Konten yang disertakan dalam permintaan pemberitahuan harus diatur ke text/xml.
wns/raw	Pemberitahuan yang dapat berisi payload kustom dan dikirimkan langsung ke aplikasi. Header Tipe Konten yang disertakan dalam permintaan pemberitahuan harus diatur ke application/octet-stream.

X-WNS-Cache-Policy

Ketika perangkat tujuan pemberitahuan offline, WNS akan menyimpan satu lencana, satu kotak, dan satu pemberitahuan toast untuk setiap URI saluran. Secara bawaan, pemberitahuan mentah tidak disimpan sementara, tetapi jika penembolokan pemberitahuan mentah diaktifkan, satu pemberitahuan mentah disimpan sementara. Item tidak disimpan dalam cache tanpa batas waktu dan akan dihilangkan setelah jangka waktu yang wajar. Jika tidak, konten yang di-cache dikirimkan ketika perangkat berikutnya online.

X-WNS-Cache-Policy: cache | no-cache

Value	Description
cache	Default. Pemberitahuan akan di-cache jika pengguna offline. Ini adalah pengaturan default untuk pemberitahuan petak peta dan lencana.
no-cache	Pemberitahuan tidak akan di-cache jika pengguna offline. Ini adalah pengaturan default untuk pemberitahuan mentah.

X-WNS-RequestForStatus

Menentukan apakah respons harus menyertakan status perangkat dan status koneksi WNS. Header ini bersifat opsional.

    X-WNS-RequestForStatus: true | false

Value	Description
true	Mengembalikan informasi status perangkat dan status pemberitahuan dalam respon.
false	Default. Jangan mengembalikan status perangkat dan status pemberitahuan.

X-WNS-Tag

Menetapkan tag label ke pemberitahuan. Tag digunakan dalam kebijakan penggantian tile dalam antrean pemberitahuan ketika aplikasi telah memilih untuk menggunakan siklus pemberitahuan. Jika pemberitahuan dengan tag ini sudah ada dalam antrean, pemberitahuan baru dengan tag yang sama menggantikannya.

Note

Header ini bersifat opsional dan hanya digunakan saat mengirim pemberitahuan petak peta.

    X-WNS-Tag: <string value>

Value	Description
nilai string	String alfanumerik tidak lebih dari 16 karakter.

X-WNS-TTL

Menentukan TTL (waktu kedaluwarsa) untuk pemberitahuan. Ini biasanya tidak diperlukan, tetapi dapat digunakan jika Anda ingin memastikan bahwa pemberitahuan Anda tidak ditampilkan lebih lambat dari waktu tertentu. TTL ditentukan dalam hitungan detik dan relatif terhadap waktu WNS menerima permintaan. Ketika TTL ditentukan, perangkat tidak akan menampilkan pemberitahuan setelah waktu tersebut. Perhatikan bahwa ini dapat mengakibatkan pemberitahuan tidak pernah ditampilkan sama sekali jika TTL terlalu pendek. Secara umum, waktu kedaluwarsa akan diukur dalam setidaknya menit.

Header ini bersifat opsional. Jika tidak ada nilai yang ditentukan, pemberitahuan tidak kedaluwarsa dan akan diganti di bawah skema penggantian pemberitahuan normal.

X-WNS-TTL: <integer value>

Value	Description
nilai bilangan bulat	Masa pakai pemberitahuan, dalam hitungan detik, setelah WNS menerima permintaan.

X-WNS-SuppressPopup

Note

Untuk aplikasi Windows Phone Store, Anda memiliki opsi untuk menghilangkan tampilan UI pemberitahuan toast, dengan mengirimkan pemberitahuan langsung ke Action Center. Ini memungkinkan pemberitahuan Anda dikirimkan secara diam-diam, opsi yang berpotensi unggul untuk pemberitahuan yang kurang mendesak. Header ini bersifat opsional dan hanya digunakan pada saluran Windows Phone. Jika Anda menyertakan header ini pada saluran Windows, pemberitahuan Anda akan dihilangkan dan Anda akan menerima respons kesalahan dari WNS.

X-WNS-SuppressPopup: true | palsu

Value	Description
true	Kirim pemberitahuan toast langsung ke pusat tindakan; jangan naikkan UI toast.
false	Default. Naikkan UI toast serta tambahkan pemberitahuan ke pusat tindakan.

X-WNS-Group

Note

Pusat tindakan untuk aplikasi Windows Phone Store dapat menampilkan beberapa pemberitahuan toast dengan tag yang sama hanya jika mereka diberi label sebagai anggota dari grup yang berbeda. Misalnya, pertimbangkan aplikasi buku resep. Setiap resep akan diidentifikasi oleh tag. Roti panggang yang mengandung komentar tentang resep tersebut akan memiliki tag resep, tetapi dengan label grup komentar. Roti panggang yang berisi peringkat untuk resep itu akan kembali memiliki tag resep itu, tetapi akan memiliki label grup peringkat. Label grup yang berbeda tersebut memungkinkan kedua pemberitahuan toast ditampilkan sekaligus di pusat notifikasi. Header ini bersifat opsional.

X-WNS-Group: <string value>

Value	Description
nilai string	String alfanumerik tidak lebih dari 16 karakter.

X-WNS-Match

Note

Digunakan dengan metode HTTP DELETE untuk menghapus toast tertentu, sekumpulan toast (dengan tag atau grup), atau semua toast dari pusat aksi untuk aplikasi di Windows Phone Store. Header ini dapat menentukan grup, tag, atau keduanya. Header ini diperlukan dalam permintaan pemberitahuan HTTP DELETE. Payload apa pun yang disertakan dengan permintaan pemberitahuan ini diabaikan.

X-WNS-Match: type:wns/toast; group=<string value>; tag=<string value> | type:wns/toast; group=<string value> | type:wns/toast; tag=<string value> | type:wns/toast; semua

Value	Description
type:wns/toast; group=<string value>; tag=<string value>	Hapus satu pemberitahuan yang berlabel dengan tag dan grup yang sama persis.
type:wns/toast; group=<string value>	Hapus semua pemberitahuan yang diberi label dengan grup yang ditentukan.
type:wns/toast; tag=<string value>	Hapus semua pemberitahuan yang diberi label dengan tag yang ditentukan.
type:wns/toast;all	Hapus semua pemberitahuan aplikasi Anda dari pusat tindakan.

Mengirim respons pemberitahuan

Setelah WNS memproses permintaan pemberitahuan, WNS mengirimkan pesan HTTP sebagai respons. Bagian ini membahas parameter dan header yang dapat ditemukan dalam respons tersebut.

Parameter respons

Nama Header	Required	Description
X-WNS-Debug-Trace	FALSE	Informasi debugging yang harus dicatat untuk membantu menyelesaikan masalah ketika melaporkan sebuah problem.
X-WNS-DeviceConnectionStatus	FALSE	Status perangkat, dikembalikan hanya jika diminta dalam permintaan pemberitahuan melalui header X-WNS-RequestForStatus.
X-WNS-Error-Description	FALSE	String kesalahan yang dapat dibaca manusia dan perlu dicatat untuk membantu pelacakan kesalahan.
X-WNS-Msg-ID	FALSE	Pengidentifikasi unik untuk pemberitahuan, digunakan untuk keperluan debug. Saat melaporkan masalah, informasi ini harus dicatat untuk membantu dalam pemecahan masalah.
X-WNS-Status	FALSE	Menunjukkan apakah WNS berhasil menerima dan memproses pemberitahuan. Saat melaporkan masalah, informasi ini harus dicatat untuk membantu dalam pemecahan masalah.
MS-CV	FALSE	Informasi debugging yang harus dicatat untuk membantu menyelesaikan masalah ketika melaporkan sebuah problem.

X-WNS-Debug-Trace

Header ini mengembalikan informasi kesalahan yang berguna dalam bentuk string. Sebaiknya header ini dicatat untuk membantu pengembang men-debug masalah. Header ini, bersama dengan header X-WNS-Msg-ID dan MS-CV, diperlukan saat melaporkan masalah ke WNS.

X-WNS-Debug-Trace: <string value>

Value	Description
nilai string	String alfanumerik.

X-WNS-DeviceConnectionStatus

Header ini mengembalikan status perangkat ke aplikasi yang memanggil, jika diminta di header X-WNS-RequestForStatus permintaan notifikasi.

X-WNS-DeviceConnectionStatus: tersambung | terputus | terputus sementara

Value	Description
connected	Perangkat sedang online dan terhubung ke WNS.
disconnected	Perangkat offline dan tidak tersambung ke WNS.
tempconnected (tidak digunakan lagi)	Perangkat untuk sementara kehilangan koneksi ke WNS, misalnya ketika koneksi 3G terputus atau sakelar nirkabel pada laptop dilemparkan. Ini dilihat oleh Platform Klien Pemberitahuan sebagai gangguan sementara daripada pemutusan sambungan yang disengaja.

X-WNS-Error-Description

Header ini menyediakan pesan kesalahan yang mudah dibaca yang harus dicatat untuk membantu pemecahan masalah.

X-WNS-Error-Description: <string value>

Value	Description
nilai string	String alfanumerik.

X-WNS-Msg-ID

Header ini digunakan untuk menyediakan pemanggil dengan ID untuk pemberitahuan. Kami menyarankan agar header ini dicatat untuk membantu men-debug masalah. Header ini, bersama dengan X-WNS-Debug-Trace dan MS-CV, diperlukan saat melaporkan masalah ke WNS.

X-WNS-Msg-ID: <string value>

Value	Description
nilai string	String alfanumerik tidak lebih dari 16 karakter.

X-WNS-Status

Header ini menjelaskan cara WNS menangani permintaan pemberitahuan. Ini dapat digunakan daripada menafsirkan kode respons sebagai keberhasilan atau kegagalan.

X-WNS-Status: diterima | dibatalkan | dibatasi saluran

Value	Description
received	Pemberitahuan diterima dan diproses oleh WNS. Catatan: Ini tidak menjamin bahwa perangkat menerima pemberitahuan.
dropped	Pemberitahuan dihilangkan secara eksplisit karena kesalahan atau karena klien secara eksplisit menolak pemberitahuan ini. Pemberitahuan toast juga tidak akan ditampilkan jika perangkat offline.
channelthrottled	Pemberitahuan dihilangkan karena server aplikasi melebihi batas tarif untuk saluran tertentu ini.

MS-CV

Header ini menyediakan Vektor Korelasi yang terkait dengan permintaan yang terutama digunakan untuk penelusuran kesalahan. Jika CV disediakan sebagai bagian dari permintaan, maka WNS akan menggunakan nilai ini, jika tidak, WNS akan menghasilkan dan merespons kembali dengan CV. Header ini, bersama dengan header X-WNS-Debug-Trace dan X-WNS-Msg-ID, diperlukan saat melaporkan masalah ke WNS.

Important

Buat CV baru untuk setiap permintaan pemberitahuan push jika Anda menyediakan CV Anda sendiri.

MS-CV: <string value>

Value	Description
nilai tipe string	Mengikuti standar Vektor Korelasi

Kode respons

Setiap pesan HTTP berisi salah satu kode respons ini. WNS merekomendasikan agar pengembang mencatat kode respons untuk digunakan dalam penelusuran kesalahan. Ketika pengembang melaporkan masalah ke WNS, mereka diharuskan untuk memberikan kode respons dan informasi header.

Kode respons HTTP	Description	Tindakan yang direkomendasikan
200 OK (Permintaan berhasil)	Pemberitahuan diterima oleh WNS.	Tidak diperlukan.
400 Permintaan Tidak Valid	Satu atau beberapa header ditentukan secara salah atau bertentangan dengan header lain.	Catat detail permintaan Anda. Periksa permintaan Anda dan bandingkan dengan dokumentasi ini.
401 Tidak Sah	Layanan awan tidak menunjukkan tiket autentikasi yang valid. Tiket OAuth mungkin tidak valid.	Minta token akses yang valid dengan mengautentikasi layanan cloud Anda menggunakan permintaan token akses.
403 Dilarang	Layanan awan tidak berwenang untuk mengirim pemberitahuan ke URI ini meskipun diautentikasi.	Token akses yang disediakan dalam permintaan tidak cocok dengan kredensial aplikasi yang meminta URI saluran. Pastikan nama paket Anda dalam manifes aplikasi anda cocok dengan kredensial layanan cloud yang diberikan kepada aplikasi Anda di Dasbor.
404 Tidak ditemukan	URI saluran tidak valid atau tidak dikenali oleh WNS.	Catat detail permintaan Anda. Jangan kirim pemberitahuan lebih lanjut ke saluran ini; pemberitahuan ke alamat ini akan gagal.
Metode 405 Tidak Diizinkan	Metode tidak valid (GET, CREATE); hanya POST (Windows atau Windows Phone) atau DELETE (khusus Windows Phone) yang diizinkan.	Catat detail permintaan Anda. Beralih menggunakan HTTP POST.
406 Tidak Dapat Diterima	Layanan cloud melebihi batas pembatasannya.	Silakan kirim permintaan Anda setelah nilai header Retry-After dalam respons
410 Hilang	Saluran telah kedaluwarsa.	Catat detail permintaan Anda. Jangan kirim pemberitahuan lebih lanjut ke saluran ini. Minta aplikasi Anda meminta URI saluran baru.
Domain 410 Diblokir	Domain pengirim telah diblokir oleh WNS.	Jangan kirim pemberitahuan lebih lanjut ke saluran ini. Domain pengiriman telah diblokir oleh WNS untuk menyalahgunakan pemberitahuan push.
Entitas Permintaan 413 Terlalu Besar	Payload pemberitahuan melebihi batas ukuran 5000 byte.	Catat detail permintaan Anda. Periksa payload untuk memastikan ukurannya berada dalam batas yang ditetapkan.
Kesalahan Server Internal 500	Kegagalan internal menyebabkan pengiriman pemberitahuan gagal.	Catat detail permintaan Anda. Laporkan masalah ini melalui forum pengembang.
503 Layanan Tidak Tersedia	Server saat ini tidak tersedia.	Catat detail permintaan Anda. Laporkan masalah ini melalui forum pengembang. Jika header Retry-After diamati, silakan kirim permintaan Anda setelah nilai header Retry-After dalam respons.

Fitur HTTP yang tidak didukung

Antarmuka Web WNS mendukung HTTP 1.1 tetapi tidak mendukung fitur berikut:

• Chunking
• Pipelining (POST tidak idempoten)
• Meskipun didukung, pengembang harus menonaktifkan Expect-100 karena memperkenalkan latensi saat mengirim pemberitahuan.