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 gambaran umum Windows Push Notification Services (WNS) untuk diskusi konseptual pemberitahuan push dan konsep, persyaratan, dan operasi WNS.

Meminta dan menerima token akses

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

Permintaan 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	Wajib	Deskripsi
grant_type	BENAR	Harus diatur ke client_credentials.
client_id	BENAR	Pengidentifikasi keamanan paket (SID) untuk layanan awan Anda seperti yang ditetapkan saat Anda mendaftarkan aplikasi Anda dengan Microsoft Store.
client_secret	BENAR	Kunci rahasia untuk layanan awan Anda seperti yang ditetapkan saat Anda mendaftarkan aplikasi Anda dengan Microsoft Store.
cakupan	BENAR	Harus disetel ke notify.windows.com

Respons 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	Wajib	Deskripsi
access_token	BENAR	Token akses yang akan digunakan layanan cloud saat mengirim pemberitahuan.
token_type	SALAH	Selalu dikembalikan sebagai bearer.

Kode respons

Kode respons HTTP	Deskripsi
200 OK	Permintaan berhasil.
400 Permintaan Buruk	Autentikasi gagal. Lihat draf OAuth Permintaan komentar (RFC) untuk parameter respons.

Contoh

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

Nama header	Wajib	Deskripsi
Authorization	BENAR	Header otorisasi HTTP standar yang digunakan untuk mengautentikasi permintaan pemberitahuan Anda. Layanan cloud Anda menyediakan token aksesnya di header ini.
Content-Type	BENAR	Header otorisasi HTTP standar. Untuk pemberitahuan toast, petak peta, dan lencana, header ini harus diatur ke text/xml. Untuk pemberitahuan mentah, header ini harus diatur ke application/octet-stream.
Panjang-Konten	BENAR	Header otorisasi HTTP standar untuk menunjukkan ukuran payload permintaan.
Tipe X-WNS	BENAR	Menentukan jenis pemberitahuan dalam payload: petak peta, roti panggang, lencana, atau mentah.
X-WNS-Cache-Policy	SALAH	Mengaktifkan atau menonaktifkan penembolokan pemberitahuan. Header ini hanya berlaku untuk petak peta, lencana, dan pemberitahuan mentah.
X-WNS-RequestForStatus	SALAH	Meminta status perangkat dan status koneksi WNS dalam respons pemberitahuan.
X-WNS-Tag	SALAH	String yang digunakan untuk memberikan pemberitahuan dengan label identifikasi, digunakan untuk petak peta yang mendukung antrean pemberitahuan. Header ini hanya berlaku untuk pemberitahuan petak peta.
X-WNS-TTL	SALAH	Nilai bilangan bulat, dinyatakan dalam hitungan detik, yang menentukan waktu hidup (TTL).
MS-CV	SALAH	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>

Tipe X-WNS

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

Nilai	Deskripsi
wns/lencana	Pemberitahuan untuk membuat overlay lencana pada petak peta. Header Tipe Konten yang disertakan dalam permintaan pemberitahuan harus diatur ke text/xml.
wns/petak peta	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 target pemberitahuan offline, WNS akan menyimpan satu lencana, satu petak peta, dan satu pemberitahuan toast untuk setiap URI saluran. Secara default, pemberitahuan mentah tidak di-cache, tetapi jika penembolokan pemberitahuan mentah diaktifkan, satu pemberitahuan mentah di-cache. 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

Nilai	Deskripsi
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

Nilai	Deskripsi
benar	Mengembalikan status perangkat dan status pemberitahuan dalam respons.
salah	Default. Jangan mengembalikan status perangkat dan status pemberitahuan.

X-WNS-Tag

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

Catatan

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

    X-WNS-Tag: <string value>

Nilai	Deskripsi
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>

Nilai	Deskripsi
nilai bilangan bulat	Masa pakai pemberitahuan, dalam hitungan detik, setelah WNS menerima permintaan.

X-WNS-SuppressPopup

Catatan

Untuk aplikasi Windows Telepon Store, Anda memiliki opsi untuk menekan UI pemberitahuan toast, sebagai gantinya mengirim pemberitahuan langsung ke pusat tindakan. 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 Telepon Windows. 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

Nilai	Deskripsi
benar	Kirim pemberitahuan toast langsung ke pusat tindakan; jangan naikkan UI toast.
salah	Default. Naikkan UI toast serta tambahkan pemberitahuan ke pusat tindakan.

X-WNS-Group

Catatan

Pusat tindakan untuk aplikasi Windows Telepon Store dapat menampilkan beberapa pemberitahuan toast dengan tag yang sama hanya jika diberi label sebagai milik grup yang berbeda. Misalnya, pertimbangkan aplikasi buku resep. Setiap resep akan diidentifikasi oleh tag. Roti panggang yang berisi komentar pada resep tersebut akan memiliki tag resep, tetapi 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 akan memungkinkan kedua pemberitahuan toast ditampilkan sekaligus di pusat tindakan. Header ini bersifat opsional.

X-WNS-Group: <string value>

Nilai	Deskripsi
nilai string	String alfanumerik tidak lebih dari 16 karakter.

X-WNS-Match

Catatan

Digunakan dengan metode HTTP DELETE untuk menghapus toast tertentu, sekumpulan roti panggang (dengan tag atau grup), atau semua toast dari pusat tindakan untuk aplikasi Windows Telepon 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

Nilai	Deskripsi
type:wns/toast; group=<string value>; tag=<string value>	Hapus satu pemberitahuan berlabel dengan tag dan grup yang ditentukan.
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; Semua	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	Wajib	Deskripsi
X-WNS-Debug-Trace	SALAH	Informasi penelusuran kesalahan yang harus dicatat untuk membantu memecahkan masalah saat melaporkan masalah.
X-WNS-Device Koneksi ionStatus	SALAH	Status perangkat, dikembalikan hanya jika diminta dalam permintaan pemberitahuan melalui header X-WNS-RequestForStatus.
X-WNS-Error-Description	SALAH	String kesalahan yang dapat dibaca manusia yang harus dicatat untuk membantu penelusuran kesalahan.
X-WNS-Msg-ID	SALAH	Pengidentifikasi unik untuk pemberitahuan, digunakan untuk tujuan penelusuran kesalahan. Saat melaporkan masalah, informasi ini harus dicatat untuk membantu dalam pemecahan masalah.
X-WNS-Status	SALAH	Menunjukkan apakah WNS berhasil menerima dan memproses pemberitahuan. Saat melaporkan masalah, informasi ini harus dicatat untuk membantu dalam pemecahan masalah.
MS-CV	SALAH	Informasi penelusuran kesalahan yang harus dicatat untuk membantu memecahkan masalah saat melaporkan masalah.

X-WNS-Debug-Trace

Header ini mengembalikan informasi penelusuran kesalahan yang berguna sebagai 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>

Nilai	Deskripsi
nilai string	String alfanumerik.

X-WNS-Device Koneksi ionStatus

Header ini mengembalikan status perangkat ke aplikasi panggilan, jika diminta di header X-WNS-RequestForStatus dari permintaan pemberitahuan.

X-WNS-Device Koneksi ionStatus: tersambung | terputus | tempdisconnected

Nilai	Deskripsi
Terhubung	Perangkat sedang online dan terhubung ke WNS.
Terputus	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 string kesalahan yang dapat dibaca manusia yang harus dicatat untuk membantu penelusuran kesalahan.

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

Nilai	Deskripsi
nilai string	String alfanumerik.

X-WNS-Msg-ID

Header ini digunakan untuk menyediakan pemanggil dengan pengidentifikasi 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>

Nilai	Deskripsi
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 | dihilangkan | channelthrottled

Nilai	Deskripsi
diterima	Pemberitahuan diterima dan diproses oleh WNS. Catatan: Ini tidak menjamin bahwa perangkat menerima pemberitahuan.
Menjatuhkan	Pemberitahuan dihilangkan secara eksplisit karena kesalahan atau karena klien secara eksplisit menolak pemberitahuan ini. Pemberitahuan toast juga akan dihilangkan 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.

Penting

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

MS-CV: <string value>

Nilai	Deskripsi
nilai 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	Deskripsi	Tindakan yang direkomendasikan
200 OK	Pemberitahuan diterima oleh WNS.	Tidak diperlukan.
400 Permintaan Buruk	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 Telepon) atau DELETE (hanya Windows Telepon) 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 Coba Lagi-Setelah dalam respons
410 Hilang	Saluran 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 payload berada dalam batasan ukuran.
500 Kesalahan Server Internal	Kegagalan internal menyebabkan pengiriman pemberitahuan gagal.	Catat detail permintaan Anda. Laporkan masalah ini melalui forum pengembang.
503 Layanan Tidak Tersedia	Saat ini server tidak tersedia.	Catat detail permintaan Anda. Laporkan masalah ini melalui forum pengembang. Jika header Coba Lagi-Setelah diamati, silakan kirim permintaan Anda setelah nilai header Coba Lagi-Setelah dalam respons.

Fitur HTTP yang tidak didukung

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

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