Push bildirim hizmeti isteği ve yanıt üst bilgisi (Windows Çalışma Zamanı uygulamaları)

Bu konuda, push bildirimi göndermek için gereken hizmet-hizmet web API'leri ve protokolleri açıklanmaktadır.

Anında iletme bildirimleri ve WNS kavramları, gereksinimleri ve işlemleri hakkında kavramsal bir tartışma için Windows Anında İletme Bildirimi Hizmetleri (WNS) genel bakışına bakın.

Erişim belirteci isteme ve alma

Bu bölümde, WNS ile kimlik doğrulaması yaptığınızda dahil olan istek ve yanıt parametreleri açıklanmaktadır.

Erişim belirteci isteği

Bulut hizmetinin kimliğini doğrulamak ve karşılığında bir erişim belirteci almak için WNS'ye bir HTTP isteği gönderilir. İstek, Güvenli Yuva Katmanı (SSL) kullanılarak verilir https://login.live.com/accesstoken.srf .

Erişim belirteci isteği parametreleri

Bulut hizmeti bu gerekli parametreleri HTTP isteği gövdesinde "application/x-www-form-urlencoded" biçimini kullanarak gönderir. Tüm parametrelerin URL ile kodlandığından emin olmanız gerekir.

Parameter	Required	Description
grant_type	TRUE	client_credentialsolarak ayarlanmalıdır.
client_id	TRUE	Uygulamanızı Microsoft Store'a kaydettiğinizde atanan bulut hizmetiniz için paket güvenlik tanımlayıcısı (SID).
client_secret	TRUE	Uygulamanızı Microsoft Store'a kaydettiğinizde atanan bulut hizmetiniz için gizli anahtar.
scope	TRUE	Şu şekilde ayarlanmalıdır: notify.windows.com

Erişim belirteci yanıtı

WNS, bulut hizmetinin kimliğini doğrular ve başarılı olursa erişim belirteci de dahil olmak üzere "200 Tamam" ile yanıt verir. Aksi takdirde WNS, OAuth 2.0 protokol taslağında açıklandığı gibi uygun bir HTTP hata koduyla yanıt verir.

Erişim belirteci yanıt parametreleri

Bulut hizmetinin kimliği başarıyla doğrulandıysa HTTP yanıtında bir erişim belirteci döndürülür. Bu erişim belirteci süresi dolana kadar bildirim isteklerinde kullanılabilir. HTTP yanıtı "application/json" medya türünü kullanır.

Parameter	Required	Description
access_token	TRUE	Bulut hizmetinin bildirim gönderirken kullanacağı erişim belirteci.
token_type	FALSE	Her zaman bearerolarak döndürülür.

Yanıt kodu

HTTP yanıt kodu	Description
200 Tamam	İstek başarılı oldu.
400 Hatalı İstek	Kimlik doğrulaması başarısız oldu. Yanıt parametreleri için açıklama isteği (RFC) OAuth taslağına bakın.

Example

Aşağıda başarılı bir kimlik doğrulama yanıtı örneği gösterilmektedir:

 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
 }

Bildirim isteği gönderme ve yanıt alma

Bu bölümde, WNS'ye bir bildirim göndermek için bir HTTP isteğinde yer alan üst bilgiler ve yanıta dahil olan üst bilgiler açıklanmaktadır.

• Bildirim isteği gönder
• Bildirim yanıtı gönder
• Desteklenmeyen HTTP özellikleri

Bildirim isteği gönder

Bildirim isteği gönderirken, çağıran uygulama SSL üzerinden kanal Tekdüzen Kaynak Tanımlayıcısı'na (URI) yönelik bir HTTP isteğinde bulunur. "content-Length", istekte belirtilmesi gereken standart bir HTTP üst bilgisidir. Diğer tüm standart başlıklar ya isteğe bağlıdır ya da desteklenmez.

Ayrıca, burada listelenen özel istek üst bilgileri bildirim isteğinde kullanılabilir. Bazı üst bilgiler gerekirken, bazıları isteğe bağlıdır.

İstek parametreleri

Başlık adı	Required	Description
Authorization	TRUE	Bildirim isteğinizin kimliğini doğrulamak için kullanılan standart HTTP yetkilendirme üst bilgisi. Bulut hizmetiniz erişim belirtecini bu üst bilgide sağlar.
Content-Type	TRUE	Standart HTTP yetkilendirme üst bilgisi. Tost, kutucuk ve rozet bildirimleri için bu üst bilgi text/xmlolarak ayarlanmalıdır. Ham bildirimler için bu üst bilgi olarak application/octet-streamayarlanmalıdır.
Content-Length	TRUE	İstek yükünün boyutunu belirtmek için standart HTTP yetkilendirme üst bilgisi.
X-WNS-Type	TRUE	Yükteki bildirim türünü tanımlar: kutucuk, toast, rozet veya ham.
X-WNS-Cache-Policy	FALSE	Bildirim önbelleğe almayı etkinleştirir veya devre dışı bırakır. Bu üst bilgi yalnızca kutucuk, rozet ve ham bildirimler için geçerlidir.
X-WNS-RequestForStatus	FALSE	Bildirim yanıtında cihaz durumunu ve WNS bağlantı durumunu iste.
X-WNS-Tag	FALSE	Bildirim kuyruğunu destekleyen kutucuklar için tanımlayıcı bir etiket ile bildirim sağlamak amacıyla kullanılan dize. Bu üst bilgi yalnızca kutucuk bildirimleri için geçerlidir.
X-WNS-TTL	FALSE	Yaşam süresini (TTL) belirten saniye cinsinden ifade edilen tamsayı değeri.
MS-CV	FALSE	İsteğiniz için Bağıntı Vektörü , değeri kullanıldı.

Önemli notlar

• İçerik Uzunluğu ve İçerik Türü, isteğe diğer standart üst bilgilerin eklenip eklenmediğine bakılmaksızın istemciye teslim edilen bildirime eklenen tek standart HTTP üst bilgileridir.
• İşlev desteklenmiyorsa diğer tüm standart HTTP üst bilgileri yoksayılır veya hata döndürür.
• 2023 Şubat ayından itibaren, WNS cihaz çevrimdışı olduğunda yalnızca bir kutucuk bildirimini önbelleğe alacak.

Authorization

OAuth 2.0 yetkilendirme yöntemini izleyerek, yetkilendirme üst bilgisi, taşıyıcı belirteçleri için çağrı yapan tarafın kimlik bilgilerini belirtmek amacıyla kullanılır.

Sözdizimi, "Taşıyıcı" dize sabiti, bir boşluk karakteri ve ardından erişim belirtecinizden oluşur. Bu erişim belirteci, yukarıda açıklanan erişim belirteci isteği vererek alınır. Aynı erişim belirteci, süresi dolana kadar sonraki bildirim isteklerinde kullanılabilir.

Bu üst bilgi gereklidir.

Authorization: Bearer <access-token>

X-WNS-Type

Bunlar WNS tarafından desteklenen bildirim türleridir. Bu üst bilgi bildirim türünü ve WNS'nin bunu nasıl işlemesi gerektiğini gösterir. Bildirim istemciye ulaştıktan sonra, gerçek yük bu belirtilen türe göre doğrulanır. Bu üst bilgi gereklidir.

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

Value	Description
wns/badge	Kutucukta rozet katmanı oluşturmaya yönelik bir bildirim. Bildirim isteğine dahil edilen İçerik Türü üst bilgisi olarak text/xmlayarlanmalıdır.
wns/tile	Kutucuk içeriğini güncelleştirmek için bir bildirim. Bildirim isteğine dahil edilen İçerik Türü üst bilgisi olarak text/xmlayarlanmalıdır.
wns/toast	İstemcide kutlama yapmak için bir bildirim. Bildirim isteğine dahil edilen İçerik Türü üst bilgisi olarak text/xmlayarlanmalıdır.
wns/raw	Özel yük içerebilen ve doğrudan uygulamaya teslim edilen bir bildirim. Bildirim isteğine dahil edilen İçerik Türü üst bilgisi olarak application/octet-streamayarlanmalıdır.

X-WNS-Cache-Policy

Bildirim hedef cihazı çevrimdışı olduğunda, WNS her kanal URI'si için bir rozet, bir kutucuk ve bir uçar bildirim önbelleğe alır. Varsayılan olarak, ham bildirimler önbelleğe alınmaz, ancak ham bildirim önbelleğe alma etkinleştirilirse bir ham bildirim önbelleğe alınır. Öğeler önbellekte süresiz olarak tutulmaz ve makul bir süre sonra bırakılır. Aksi takdirde, önbelleğe alınan içerik cihaz bir sonraki çevrimiçi olduğunda teslim edilir.

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

Value	Description
cache	Default. Kullanıcı çevrimdışıysa bildirimler önbelleğe alınır. Bu, kutucuk ve rozet bildirimleri için varsayılan ayardır.
no-cache	Kullanıcı çevrimdışıysa bildirim önbelleğe alınmaz. Bu, ham bildirimler için varsayılan ayardır.

X-WNS-RequestForStatus

Yanıtın cihaz durumunu ve WNS bağlantı durumunu içermesi gerekip gerekmediğini belirtir. Bu üst bilgi isteğe bağlıdır.

    X-WNS-RequestForStatus: true | false

Value	Description
true	Yanıt olarak cihaz durumunu ve bildirim durumunu döndür.
false	Default. Cihaz durumunu ve bildirim durumunu döndürmeyin.

X-WNS-Tag

Bildirime bir etiketi atar. Etiket, uygulamanın bildirim döngüsü sistemini seçtiği durumda bildirim kuyruğundaki kutucuğu değiştirme politikasında kullanılır. Kuyrukta bu etikete sahip bir bildirim zaten varsa, aynı etikete sahip yeni bir bildirim onun yerini alır.

Note

Bu üst bilgi isteğe bağlıdır ve yalnızca kutucuk bildirimleri gönderirken kullanılır.

    X-WNS-Tag: <string value>

Value	Description
dize değeri	En fazla 16 karakterden oluşan alfasayısal dize.

X-WNS-TTL

Bildirim için TTL'yi (süre sonu) belirtir. Bu genellikle gerekli değildir, ancak bildirimlerinizin belirli bir süreden sonra görüntülenmediğinden emin olmak istiyorsanız kullanılabilir. TTL saniye cinsinden belirtilir ve WNS'nin isteği aldığı zamana göre belirlenir. Bir TTL belirtildiğinde, cihaz bu süreden sonra bildirimi görüntülemez. Bunun, TTL çok kısa olduğunda bildirimin hiçbir şekilde gösterilmeyebileceğine dikkat edin. Genel olarak, son kullanma süresi en az dakika cinsinden ölçülür.

Bu üst bilgi isteğe bağlıdır. Herhangi bir değer belirtilmezse bildirimin süresi dolmaz ve normal bildirim değiştirme düzeni altında değiştirilir.

X-WNS-TTL: <integer value>

Value	Description
tamsayı değeri	WNS isteği aldıktan sonra bildirimin geçerlilik süresi, saniye cinsinden.

X-WNS-SuppressPopup

Note

Windows Phone Mağazası uygulamaları için, bir toast bildiriminin kullanıcı arabirimini gizlemek veya bildirimi doğrudan işlem merkezine göndermek seçeneğiniz vardır. Bu, bildiriminizin sessizce teslim edilerek daha az acil bildirimler için potansiyel olarak üstün bir seçenek olmasını sağlar. Bu üst bilgi isteğe bağlıdır ve yalnızca Windows Phone kanallarında kullanılır. Bu üst bilgiyi bir Windows kanalına eklerseniz bildiriminiz bırakılır ve WNS'den bir hata yanıtı alırsınız.

X-WNS-SuppressPopup: doğru | yanlış

Value	Description
true	Bildirim bildirimini doğrudan işlem merkezine gönderin; bildirim kullanıcı arabirimini yükseltmeyin.
false	Default. Bildirim kullanıcı arabirimini yükseltin ve bildirimi işlem merkezine ekleyin.

X-WNS-Group

Note

Windows Phone Mağazası uygulamaları için bildirim merkezi, aynı etikete sahip birden çok bildirim iletisini ancak farklı gruplara ait olarak etiketlendiklerinde görüntüleyebilir. Örneğin, bir tarif kitabı uygulaması düşünün. Her tarif bir etiketle tanımlanır. Bu tarifle ilgili bir yorumu içeren bir bildirimde tarifin etiketi olur, ancak bir yorum grubu etiketi kullanılır. Bu tarif için bir derecelendirme içeren bir bildirimde yine tarifin etiketi bulunur ama ayrıca bir derecelendirme grup etiketi de bulunur. Bu farklı grup etiketleri, işlem merkezinde her iki bildirimin de aynı anda gösterilmesini sağlar. Bu üst bilgi isteğe bağlıdır.

X-WNS-Group: <string value>

Value	Description
dize değeri	En fazla 16 karakterden oluşan alfasayısal dize.

X-WNS-Match

Note

Windows Phone Mağazası uygulamaları için işlem merkezinden belirli bir bildirimi, bir dizi bildirimi (etiket veya grup tarafından) veya tüm bildirimleri kaldırmak için HTTP DELETE yöntemiyle birlikte kullanılır. Bu üst bilgi bir grup, etiket veya her ikisini de belirtebilir. Bu üst bilgi bir HTTP DELETE bildirim isteğinde gereklidir. Bu bildirim isteğine dahil edilen tüm yükler yoksayılır.

Türü:wns/toast; grup=<string value>; etiket=<string value> | türü:wns/toast; grup=<string value> | türü:wns/toast; etiket=<string value> | türü:wns/toast; tümü

Value	Description
type:wns/toast; group=<string value>; tag=<string value>	Hem belirtilen etiket hem de grupla etiketlenmiş tek bir bildirimi kaldırın.
type:wns/toast; group=<string value>	Belirtilen grupla etiketlenmiş tüm bildirimleri kaldırın.
type:wns/toast; tag=<string value>	Belirtilen etiketle etiketlenmiş tüm bildirimleri kaldırın.
type:wns/toast;all	İşlem merkezinden uygulamanızın tüm bildirimlerini temizleyin.

Bildirim yanıtı gönder

WNS bildirim isteğini işledikten sonra yanıt olarak bir HTTP iletisi gönderir. Bu bölümde, bu yanıtta bulunabilecek parametreler ve üst bilgiler ele alınmaktadır.

Yanıt parametreleri

Başlık adı	Required	Description
X-WNS-Debug-Trace	FALSE	Bir sorunu bildirirken karşılaşılan sorunları gidermeye yardımcı olmak için günlüğe kaydedilmesi gereken hata ayıklama bilgileri.
X-WNS-DeviceConnectionStatus	FALSE	Cihaz durumu, yalnızca bildirim isteğinde X-WNS-RequestForStatus başlığı aracılığıyla talep edildiğinde döndürülür.
X-WNS-Error-Description	FALSE	Hata ayıklamaya yardımcı olması için günlüğe kaydedilmesi gereken, okunabilir bir hata dizesi.
X-WNS-Msg-ID	FALSE	Hata ayıklama amacıyla kullanılan, bildirim için benzersiz bir tanımlayıcı. Sorun bildirilirken, sorun gidermeye yardımcı olması için bu bilgilerin günlüğe kaydedilmesi gerekir.
X-WNS-Status	FALSE	WNS'nin bildirimi başarıyla alıp almadığını ve işleyip işlemediğini gösterir. Sorun bildirilirken, sorun gidermeye yardımcı olması için bu bilgilerin günlüğe kaydedilmesi gerekir.
MS-CV	FALSE	Bir sorunu bildirirken karşılaşılan sorunları gidermeye yardımcı olmak için günlüğe kaydedilmesi gereken hata ayıklama bilgileri.

X-WNS-Debug-Trace

Bu üst bilgi, yararlı hata ayıklama bilgilerini dize olarak döndürür. Geliştiricilerin sorunlarda hata ayıklamasına yardımcı olmak için bu başlığın günlüğe kaydedilmesini öneririz. Bu üst bilgi, WNS'ye bir sorun bildirilirken X-WNS-Msg-ID üst bilgisi ve MS-CV ile birlikte gereklidir.

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

Value	Description
dize değeri	Alfasayısal dize.

X-WNS-DeviceConnectionStatus

Bu üst bilgi, bildirim isteğinin X-WNS-RequestForStatus üst bilgisinde talep edilirse, cihaz durumunu istekte bulunan uygulamaya döndürür.

X-WNS-DeviceConnectionStatus: bağlı | bağlantısı kesildi | geçici olarak bağlantısı kesildi

Value	Description
connected	Cihaz çevrimiçi ve WNS'ye bağlı.
disconnected	Cihaz çevrimdışı ve WNS'ye bağlı değil.
tempconnected (kullanım dışı)	Cihaz, örneğin bir 3G bağlantısı kesildiğinde veya dizüstü bilgisayarda kablosuz anahtarı kapatıldığında, WNS bağlantısını geçici olarak kaybetti. Bildirim İstemci Platformu tarafından kasıtlı bir bağlantı kesilmesi yerine geçici bir kesinti olarak görülür.

X-WNS-Error-Description

Bu başlık, insan tarafından okunabilir bir hata dizesi sağlayarak, hata ayıklamaya yardımcı olması için günlüğe kaydedilmelidir.

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

Value	Description
dize değeri	Alfasayısal dize.

X-WNS-Msg-ID

Çağırana bildirim için bir tanımlayıcı sağlamak amacıyla bu üst bilgi kullanılır. Sorunlarda hata ayıklamaya yardımcı olması için bu üst bilginin günlüğe kaydedilmesini önerdik. WNS'ye bir sorun bildirirken, bu başlık X-WNS-Debug-Trace ve MS-CV ile birlikte gereklidir.

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

Value	Description
dize değeri	En fazla 16 karakterden oluşan alfasayısal dize.

X-WNS-Status

Bu üst bilgi, WNS'nin bildirim isteğini nasıl işlediğini açıklar. Bu, yanıt kodlarını başarılı veya başarısız olarak yorumlamak yerine kullanılabilir.

X-WNS-Status: alındı | düşürüldü | kanal kısıtlamalı

Value	Description
received	Bildirim WNS tarafından alındı ve işlendi. Not: Bu, cihazın bildirimi aldığını garanti etmez.
dropped	Bir hata nedeniyle veya istemci bu bildirimleri açıkça reddettiği için bildirim açıkça bırakıldı. Cihaz çevrimdışıysa, toast bildirimleri de gönderilmez.
channelthrottled	Uygulama sunucusu bu belirli kanalın hız sınırını aştığından bildirim bırakıldı.

MS-CV

Bu üst bilgi, öncelikli olarak hata ayıklama için kullanılan istekle ilgili bir Korelasyon Vektörü sağlar. İsteğin bir parçası olarak bir CV sağlanırsa WNS bu değeri kullanır, aksi takdirde WNS bir CV oluşturup yanıt verir. Bu üst bilgi, WNS'ye bir sorun bildirilirken X-WNS-Debug-Trace ve X-WNS-Msg-ID üst bilgisi ile birlikte gereklidir.

Important

Kendi CV'nizi sağlıyorsanız, lütfen her anlık bildirim isteği için yeni bir CV oluşturun.

MS-CV: <string value>

Value	Description
dize değeri	Bağıntı Vektörü standardı

Yanıt kodları

Her HTTP iletisi bu yanıt kodlarından birini içerir. WNS, geliştiricilerin hata ayıklamada kullanmak üzere yanıt kodunu günlüğe kaydetmesini önerir. Geliştiriciler WNS'ye bir sorun bildirdiğinde yanıt kodları ve üst bilgi bilgileri sağlamaları gerekir.

HTTP yanıt kodu	Description	Önerilen eylem
200 Tamam	Bildirim WNS tarafından kabul edildi.	Gerekli değil.
400 Hatalı İstek	Bir veya daha fazla üst bilgi yanlış belirtildi veya başka bir üst bilgiyle çakışıyor.	İsteğinizin ayrıntılarını günlüğe kaydedin. İsteğinizi inceleyin ve bu belgelerle karşılaştırın.
401 Yetkisiz	Bulut hizmeti geçerli bir kimlik doğrulama bileti sunmadı. OAuth bileti geçersiz olabilir.	Erişim belirteci isteğini kullanarak bulut hizmetinizin kimliğini doğrulayarak geçerli bir erişim belirteci isteyin.
403 Yasak	Bulut hizmetinin kimliği doğrulanmış olsa bile bu URI'ye bildirim gönderme yetkisi yok.	İstekte sağlanan erişim belirteci, kanal URI'sini isteyen uygulamanın kimlik bilgileriyle eşleşmiyor. Uygulamanızın bildirimindeki paket adınızın Pano'da uygulamanıza verilen bulut hizmeti kimlik bilgileriyle eşleştiğinden emin olun.
404 Bulunamadı	Kanal URI'si geçerli değil veya WNS tarafından tanınmıyor.	İsteğinizin ayrıntılarını günlüğe kaydedin. Bu kanala daha fazla bildirim göndermeyin; bu adrese yapılan bildirimler başarısız olur.
405 Yöntemine İzin Verilmiyor	Geçersiz yöntem (GET, CREATE); yalnızca POST (Windows veya Windows Phone) veya DELETE (yalnızca Windows Phone) seçeneğine izin verilir.	İsteğinizin ayrıntılarını günlüğe kaydedin. HTTP POST kullanmaya geçin.
406 Kabul Edilemez	Bulut hizmeti kendi hız sınırlamasını aştı.	Lütfen yanıttaki Retry-After üst bilgi değerinden sonra isteğinizi gönderin
410 Gitti	Kanalın süresi doldu.	İsteğinizin ayrıntılarını günlüğe kaydedin. Bu kanala daha fazla bildirim göndermeyin. Uygulamanızın yeni bir kanal URI'sini istemesini sağlayın.
410 Etki Alanı Engellendi	Gönderen etki alanı WNS tarafından engellendi.	Bu kanala daha fazla bildirim göndermeyin. Gönderen etki alanı, anlık bildirimleri kötüye kullandığı için WNS tarafından engellendi.
413 İstek Birimi Çok Büyük	Bildirim yükü 5000 bayt boyut sınırını aşıyor.	İsteğinizin ayrıntılarını günlüğe kaydedin. Boyut sınırlamaları dahilinde olduğundan emin olmak için yükü inceleyin.
500 İç Sunucu Hatası	bir iç hata, bildirim teslimin başarısız olmasına neden oldu.	İsteğinizin ayrıntılarını günlüğe kaydedin. Bu sorunu geliştirici forumları aracılığıyla bildirin.
503 Hizmet Kullanılamıyor	Sunucu şu anda kullanılamıyor.	İsteğinizin ayrıntılarını günlüğe kaydedin. Bu sorunu geliştirici forumları aracılığıyla bildirin. Retry-After üst bilgisi gözlemleniyorsa lütfen yanıttaki Retry-After üst bilgi değerinden sonra isteğinizi gönderin.

Desteklenmeyen HTTP özellikleri

WNS Web Arabirimi HTTP 1.1'i destekler ancak aşağıdaki özellikleri desteklemez:

• Chunking
• Pipelining (POST idempotent değildir)
• Destekleniyor olsa da geliştiriciler, bildirim gönderirken gecikme süresine neden olduğundan Expect-100'i devre dışı bırakmalıdır.