Udostępnij przez

Nagłówki żądań i odpowiedzi usługi powiadomień push (aplikacje Windows Runtime)

W tym temacie opisano interfejsy API i protokoły komunikacji między usługami wymagane do wysyłania powiadomień wypychanych.

Zobacz omówienie systemu powiadomień wypychanych Windows (WNS) , aby zapoznać się z koncepcyjną dyskusją o pojęciach dotyczących powiadomień wypychanych i usług WNS, wymaganiach i działaniu.

Żądanie i otrzymanie tokenu dostępu

W tej sekcji opisano parametry żądania i odpowiedzi związane z uwierzytelnianiem w usłudze WNS.

Żądanie tokenu dostępu

Żądanie HTTP jest wysyłane do usługi WNS w celu uwierzytelnienia usługi w chmurze i pobierania tokenu dostępu w zamian. Żądanie jest wysyłane do https://login.live.com/accesstoken.srf przy użyciu protokołu Secure Sockets Layer (SSL).

Parametry żądania tokenu dostępu

Usługa w chmurze przesyła te wymagane parametry w treści żądania HTTP przy użyciu formatu "application/x-www-form-urlencoded". Upewnij się, że wszystkie parametry są kodowane za pomocą adresu URL.

Parameter Required Description
grant_type TRUE Musi być ustawione na client_credentials.
client_id TRUE Identyfikator zabezpieczeń pakietu (SID) dla usługi w chmurze przypisany podczas rejestrowania aplikacji w sklepie Microsoft Store.
client_secret TRUE Klucz tajny usługi w chmurze przypisany podczas rejestrowania aplikacji w sklepie Microsoft Store.
zakres TRUE Musi być ustawiona wartość notify.windows.com

Odpowiedź tokenu dostępu

Usługa WNS uwierzytelnia usługę w chmurze, a w przypadku powodzenia odpowiada za pomocą wartości "200 OK", w tym tokenu dostępu. W przeciwnym razie usługa WNS odpowiada odpowiednim kodem błędu HTTP zgodnie z opisem w wersji roboczej protokołu OAuth 2.0.

Parametry odpowiedzi tokenu dostępu

Token dostępu jest zwracany w odpowiedzi HTTP, jeśli usługa w chmurze została pomyślnie uwierzytelniona. Ten token dostępu może być używany w żądaniach powiadomień do momentu jego wygaśnięcia. Odpowiedź HTTP używa typu nośnika "application/json".

Parameter Required Description
access_token TRUE Token dostępu używany przez usługę w chmurze podczas wysyłania powiadomienia.
token_type FALSE Zawsze zwracane jako bearer.

Kod odpowiedzi

Kod odpowiedzi HTTP Description
200 OK Żądanie zakończyło się pomyślnie.
400 Nieprawidłowe żądanie Uwierzytelnianie nie powiodło się. Zobacz OAuth draft Request for Comments (RFC), aby uzyskać parametry odpowiedzi.

Example

Poniżej przedstawiono przykład pomyślnej odpowiedzi uwierzytelniania:

 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
 }

Wysyłanie żądania powiadomienia i odbieranie odpowiedzi

W tej sekcji opisano nagłówki związane z żądaniem HTTP do usługi WNS w celu dostarczenia powiadomienia oraz nagłówki związane z odpowiedzią.

  • Wysyłanie żądania powiadomienia
  • Wysyłanie odpowiedzi na powiadomienie
  • Nieobsługiwane funkcje HTTP

Wysyłanie żądania powiadomienia

Podczas wysyłania żądania powiadomienia aplikacja wywołująca wysyła żądanie HTTP za pośrednictwem protokołu SSL adresowane do kanału Uniform Resource Identifier (URI). "Content-Length" to standardowy nagłówek HTTP, który musi zostać określony w żądaniu. Wszystkie inne standardowe nagłówki są opcjonalne lub nieobsługiwane.

Ponadto w żądaniu powiadomień można używać niestandardowych nagłówków żądań, które są wymienione tutaj. Niektóre nagłówki są wymagane, podczas gdy inne są opcjonalne.

Parametry żądania

Nazwa nagłówka Required Description
Authorization TRUE Standardowy nagłówek autoryzacji HTTP używany do uwierzytelniania żądania powiadomień. Usługa w chmurze udostępnia token dostępu w tym nagłówku.
Content-Type TRUE Standardowy nagłówek autoryzacji HTTP. W przypadku powiadomień typu toast, kafelków i odznak ten nagłówek musi być ustawiony na wartość text/xml. W przypadku nieprzetworzonych powiadomień ten nagłówek musi być ustawiony na wartość application/octet-stream.
Content-Length TRUE Standardowy nagłówek autoryzacji HTTP, aby określić rozmiar ładunku żądania.
X-WNS-Type TRUE Definiuje typ powiadomienia w ładunku: kafelek, wyskakujące, znaczek lub nieprzetworzone.
X-WNS-Cache-Policy FALSE Włącza lub wyłącza buforowanie powiadomień. Ten nagłówek dotyczy tylko powiadomień kafelków, znaczków i surowych powiadomień.
X-WNS-RequestForStatus FALSE Żąda informacji o stanie urządzenia oraz stanie połączenia WNS w ramach odpowiedzi na powiadomienie.
X-WNS-Tag FALSE Ciąg służący do dostarczania powiadomienia z identyfikującą etykietą, używaną dla kafelków obsługujących kolejkę powiadomień. Ten nagłówek dotyczy tylko powiadomień kafelkowych.
X-WNS-TTL FALSE Wartość całkowita wyrażona w sekundach określająca czas do wygaśnięcia (TTL).
MS-CV FALSE wartość wektora korelacji użyta dla żądania.

Ważne uwagi

  • Content-Length i Content-Type to jedyne standardowe nagłówki HTTP zawarte w powiadomieniu dostarczonym do klienta, niezależnie od tego, czy inne standardowe nagłówki zostały uwzględnione w żądaniu.
  • Wszystkie inne standardowe nagłówki HTTP są ignorowane lub zwracają błąd, jeśli funkcja nie jest obsługiwana.
  • Począwszy od lutego 2023 r., usługa WNS będzie buforować tylko jedno powiadomienie kafelka, gdy urządzenie jest offline.

Authorization

Nagłówek autoryzacji służy do określania poświadczeń jednostki wywołującej, po metodę autoryzacji OAuth 2.0 dla tokenów elementu nośnego .

Składnia składa się z literału ciągu "Bearer", po którym następuje spacja, a następnie token dostępu. Ten token dostępu jest pobierany przez wystawienie żądania tokenu dostępu opisanego powyżej. Tego samego tokenu dostępu można używać w kolejnych żądaniach powiadomień, dopóki nie wygaśnie.

Ten nagłówek jest wymagany.

Authorization: Bearer <access-token>

X-WNS-Type

Są to typy powiadomień obsługiwane przez usługę WNS. Ten nagłówek wskazuje typ powiadomienia i sposób obsługi go przez usługę WNS. Po dotarciu powiadomienia do klienta rzeczywisty ładunek jest weryfikowany względem tego określonego typu. Ten nagłówek jest wymagany.

X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw
Value Description
wns/badge Powiadomienie o stworzeniu nakładki na kafelku ze znaczkiem. Nagłówek Content-Type zawarty w żądaniu powiadomienia musi być ustawiony na wartość text/xml.
wns/tile Powiadomienie o potrzebie zaktualizowania zawartości kafelka. Nagłówek Content-Type zawarty w żądaniu powiadomienia musi być ustawiony na wartość text/xml.
wns/toast Powiadomienie o wzniesieniu toastu na kliencie. Nagłówek Content-Type zawarty w żądaniu powiadomienia musi być ustawiony na wartość text/xml.
wns/raw Powiadomienie, które może zawierać niestandardową zawartość i jest dostarczane bezpośrednio do aplikacji. Nagłówek Content-Type zawarty w żądaniu powiadomienia musi być ustawiony na wartość application/octet-stream.

X-WNS-Cache-Policy

Gdy urządzenie celem powiadomień jest w trybie offline, usługa WNS będzie buforować jedną odznakę, jeden kafelek i jedno powiadomienie typu toast dla każdego identyfikatora URI kanału. Domyślnie nieprzetworzone powiadomienia nie są buforowane, ale jeśli włączono buforowanie nieprzetworzonych powiadomień, jedno nieprzetworzone powiadomienie jest buforowane. Elementy nie są przechowywane w pamięci podręcznej przez czas nieokreślony i zostaną usunięte po rozsądnym czasie. W przeciwnym razie buforowana zawartość jest dostarczana po następnym uruchomieniu urządzenia w trybie online.

X-WNS-Cache-Policy: cache | no-cache
Value Description
bufor Default. Powiadomienia będą buforowane, jeśli użytkownik jest w trybie offline. Jest to ustawienie domyślne dla powiadomień płytek i znaczków.
no-cache Powiadomienie nie będzie buforowane, jeśli użytkownik jest w trybie offline. Jest to ustawienie domyślne dla nieprzetworzonych powiadomień.

X-WNS-RequestForStatus

Określa, czy odpowiedź powinna zawierać stan urządzenia i stan połączenia WNS. Ten nagłówek jest opcjonalny.

    X-WNS-RequestForStatus: true | false
Value Description
true Zwróć status urządzenia i status powiadomienia w odpowiedzi.
false Default. Nie zwracaj stanu urządzenia i stanu powiadomienia.

X-WNS-Tag

Przypisuje tag etykietę do powiadomienia. Tag jest używany w polityce zastępowania kafelka w kolejce powiadomień, gdy aplikacja zdecydowała się na cykliczne powiadamianie. Jeśli w kolejce istnieje już powiadomienie z tym tagiem, ma miejsce nowe powiadomienie z tym samym tagiem.

Note

Ten nagłówek jest opcjonalny i używany tylko podczas wysyłania powiadomień kafelków.

    X-WNS-Tag: <string value>
Value Description
wartość ciągu Ciąg alfanumeryczny o długości maksymalnie 16 znaków.

X-WNS-TTL

Określa TTL (czas wygaśnięcia) powiadomienia. Zazwyczaj nie jest to konieczne, ale można go użyć, jeśli chcesz upewnić się, że powiadomienia nie są wyświetlane później niż określony czas. Wartość TTL jest określona w sekundach i jest względna do czasu otrzymania żądania przez usługę WNS. Po określeniu TTL, urządzenie nie wyświetli powiadomienia po tym czasie. Należy pamiętać, że może to spowodować, że powiadomienie nigdy nie będzie wyświetlane, jeśli czas wygaśnięcia jest zbyt krótki. Ogólnie rzecz biorąc, czas wygaśnięcia będzie mierzony w co najmniej minutach.

Ten nagłówek jest opcjonalny. Jeśli żadna wartość nie zostanie określona, powiadomienie nie wygaśnie i zostanie zastąpione w normalnym schemacie wymiany powiadomień.

X-WNS-TTL: <integer value>

Value Description
Wartość całkowita Okres życia powiadomienia, w sekundach, po tym jak WNS odbierze żądanie.

X-WNS-SuppressPopup

Note

W przypadku aplikacji ze Sklepu Windows Phone możesz pominąć wyświetlanie powiadomień toast, wysyłając powiadomienie bezpośrednio do Centrum akcji. Dzięki temu powiadomienie będzie dostarczane w trybie dyskretnym— potencjalnie lepsza opcja dla mniej pilnych powiadomień. Ten nagłówek jest opcjonalny i używany tylko w kanałach systemu Windows Phone. Jeśli ten nagłówek zostanie uwzględniony w kanale systemu Windows, powiadomienie zostanie porzucone i otrzymasz odpowiedź o błędzie z usługi WNS.

X-WNS-SuppressPopup: true | fałszywy

Value Description
true Wyślij powiadomienie toast bezpośrednio do centrum akcji; nie wywołuj interfejsu toast.
false Default. Podnieś wyskakujące interfejs użytkownika, a także dodaj powiadomienie do centrum akcji.

X-WNS-Group

Note

Centrum akcji dla aplikacji ze Sklepu Windows Phone może wyświetlać wiele wyskakowanych powiadomień z tym samym tagiem tylko wtedy, gdy są one oznaczone jako należące do różnych grup. Rozważmy na przykład aplikację z przepisami. Każdy przepis zostanie zidentyfikowany przez tag. Wiadomość zawierająca komentarz do tego przepisu będzie miała tag przepisu, lecz etykietę grupy komentarzy. Komunikat zawierający ocenę dla tego przepisu będzie miał ponownie tag tego przepisu oraz etykietę grupy oceny. Te różne etykiety grup umożliwiają, aby powiadomienia typu toast były wyświetlane jednocześnie w centrum akcji. Ten nagłówek jest opcjonalny.

X-WNS-Group: <string value>

Value Description
wartość ciągu Ciąg alfanumeryczny o długości maksymalnie 16 znaków.

X-WNS-Match

Note

Używana z metodą HTTP DELETE do usuwania określonego powiadomienia, zestawu powiadomień (według tagu lub grupy) lub wszystkich powiadomień z Centrum operacji dla aplikacji ze sklepu Microsoft dla telefonów z Windows. Ten nagłówek może określać grupę, tag lub oba te elementy. Ten nagłówek jest wymagany w żądaniu powiadomienia HTTP DELETE. Każdy ładunek dołączony do tego żądania powiadomienia jest ignorowany.

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

Value Description
type:wns/toast; group =<string value>; tag =<string value> Usuń pojedyncze powiadomienie oznaczone zarówno określonym tagiem, jak i grupą.
type:wns/toast; group =<string value> Usuń wszystkie powiadomienia oznaczone określoną grupą.
type:wns/toast; tag =<string value> Usuń wszystkie powiadomienia oznaczone określonym tagiem.
type:wns/toast;all Wyczyść wszystkie powiadomienia aplikacji z centrum akcji.

Wysyłanie odpowiedzi na powiadomienie

Gdy usługa WNS przetworzy żądanie powiadomienia, wysyła komunikat HTTP w odpowiedzi. W tej sekcji omówiono parametry i nagłówki, które można znaleźć w tej odpowiedzi.

Parametry odpowiedzi

Nazwa nagłówka Required Description
X-WNS-Debug-Trace FALSE Informacje debugowania, które powinny być rejestrowane, aby ułatwić rozwiązywanie problemów podczas zgłaszania problemu.
X-WNS-DeviceConnectionStatus FALSE Stan urządzenia jest zwracany tylko wtedy, gdy został zażądany w żądaniu powiadomienia poprzez nagłówek X-WNS-RequestForStatus.
X-WNS-Error-Description FALSE Ciąg błędu czytelny dla człowieka, który powinien być rejestrowany, aby ułatwić debugowanie.
X-WNS-Msg-ID FALSE Unikatowy identyfikator powiadomienia używany do celów debugowania. Podczas zgłaszania problemu te informacje powinny być rejestrowane w celu ułatwienia rozwiązywania problemów.
X-WNS-Status FALSE Wskazuje, czy WNS pomyślnie otrzymała i przetworzyła powiadomienie. Podczas zgłaszania problemu te informacje powinny być rejestrowane w celu ułatwienia rozwiązywania problemów.
MS-CV FALSE Informacje debugowania, które powinny być rejestrowane, aby ułatwić rozwiązywanie problemów podczas zgłaszania problemu.

X-WNS-Debug-Trace

Ten nagłówek zwraca przydatne informacje debugowania jako ciąg. Zalecamy zapisywanie tego nagłówka, aby pomóc deweloperom w debugowaniu problemów. Ten nagłówek, łącznie z nagłówkiem X-WNS-Msg-ID i MS-CV, jest wymagany podczas raportowania problemu do usługi WNS.

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

Value Description
wartość ciągu Ciąg alfanumeryczny.

X-WNS-DeviceConnectionStatus

Ten nagłówek zwraca stan urządzenia do aplikacji wywołującej, jeśli jest to wymagane w nagłówku X-WNS-RequestForStatus żądania powiadomienia.

X-WNS-DeviceConnectionStatus: połączone | rozłączone | tymczasowo rozłączone

Value Description
connected Urządzenie jest w trybie online i połączone z usługą WNS.
disconnected Urządzenie jest w trybie offline i nie jest połączone z usługą WNS.
tempconnected (przestarzałe) Urządzenie tymczasowo utraciło połączenie z usługą WNS, na przykład gdy połączenie 3G zostanie przerwane lub przełącznik bezprzewodowy na laptopie zostanie przełączony. Platforma klienta powiadomień postrzega to jako tymczasową przerwę, a nie celowe rozłączenie.

X-WNS-Error-Description

Ten nagłówek zawiera czytelny dla człowieka ciąg błędu, który powinien być rejestrowany, aby ułatwić debugowanie.

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

Value Description
wartość ciągu Ciąg alfanumeryczny.

X-WNS-Msg-ID

Ten nagłówek służy do dostarczenia dzwoniącemu identyfikatora powiadomienia. Zalecamy zarejestrowanie tego nagłówka w celu ułatwienia debugowania problemów. Ten nagłówek wraz z X-WNS-Debug-Trace i MS-CV są wymagane podczas zgłaszania problemu do usługi WNS.

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

Value Description
wartość ciągu Ciąg alfanumeryczny o długości maksymalnie 16 znaków.

X-WNS-Status

W tym nagłówku opisano sposób obsługi żądania powiadomienia przez usługę WNS. Może to być używane zamiast interpretować kody odpowiedzi jako powodzenie lub niepowodzenie.

Stan X-WNS: odebrany | porzucony | ograniczenie kanału

Value Description
received Powiadomienie zostało odebrane i przetworzone przez usługę WNS. Uwaga: nie gwarantuje to, że urządzenie otrzymało powiadomienie.
dropped Powiadomienie zostało wyraźnie usunięte z powodu błędu lub ponieważ klient wyraźnie odrzucił te powiadomienia. Powiadomienia typu toast również zostaną odrzucone, jeśli urządzenie jest w trybie offline.
channelthrottled Powiadomienie zostało porzucone, ponieważ serwer aplikacji przekroczył limit szybkości dla tego konkretnego kanału.

MS-CV

Ten nagłówek zawiera wektor korelacji związany z żądaniem, które jest używane głównie do debugowania. Jeśli CV jest podane w ramach żądania, WNS użyje tej wartości, a w przeciwnym razie WNS wygeneruje i odpowie, dołączając CV. Ten nagłówek wraz z nagłówkiem X-WNS-Debug-Trace i X-WNS-Msg-ID są wymagane podczas raportowania problemu do usługi WNS.

Important

Proszę generować nowe CV przy każdym żądaniu powiadomienia push, jeśli dostarczasz własne CV.

MS-CV: <string value>

Value Description
wartość ciągu Jest zgodny ze standardem Correlation Vector

Kody odpowiedzi

Każdy komunikat HTTP zawiera jeden z tych kodów odpowiedzi. Usługa WNS zaleca, aby deweloperzy rejestrowali kod odpowiedzi do użycia podczas debugowania. Gdy deweloperzy zgłaszają problem w usłudze WNS, muszą podać kody odpowiedzi i informacje nagłówkowe.

Kod odpowiedzi HTTP Description Zalecana akcja
200 OK Powiadomienie zostało zaakceptowane przez WNS. Żaden z nich nie jest wymagany.
400 Nieprawidłowe żądanie Co najmniej jeden nagłówek został niepoprawnie określony lub pozostaje w konflikcie z innym nagłówkiem. Zarejestruj szczegóły żądania. Sprawdź żądanie i porównaj je z tą dokumentacją.
401 Brak autoryzacji Usługa w chmurze nie przedstawiła prawidłowego biletu uwierzytelniania. Bilet OAuth może być nieprawidłowy. Zażądaj prawidłowego tokenu dostępu, uwierzytelniając usługę w chmurze przy użyciu żądania tokenu dostępu.
403 Zabronione Usługi chmurowe nie mają autoryzacji do wysyłania powiadomienia do tego identyfikatora URI, mimo że są uwierzytelnione. Token dostępu podany w żądaniu nie pasuje do danych uwierzytelniających aplikacji, która zażądała identyfikatora URI kanału. Upewnij się, że nazwa pakietu w manifeście aplikacji jest zgodna z poświadczeniami usługi w chmurze podanymi dla aplikacji na pulpicie nawigacyjnym.
404 Nie znaleziono Identyfikator URI kanału jest nieprawidłowy lub nie jest rozpoznawany przez usługę WNS. Zarejestruj szczegóły żądania. Nie wysyłaj dalszych powiadomień do tego kanału; powiadomienia do tego adresu nie powiedzie się.
Niedozwolona metoda 405 Nieprawidłowa metoda (GET, CREATE); dozwolona jest tylko metoda POST (Windows lub Windows Phone) lub DELETE (tylko Windows Phone). Zarejestruj szczegóły żądania. Przełącz się na przy użyciu protokołu HTTP POST.
406 Nie do przyjęcia Usługa w chmurze przekroczyła limit ograniczenia przepustowości. Wyślij żądanie po wartości nagłówka Retry-After w odpowiedzi
410 Zniknął Kanał wygasł. Zarejestruj szczegóły żądania. Nie wysyłaj dalszych powiadomień do tego kanału. Poproś aplikację o nowy identyfikator URI kanału.
Zablokowano domenę 410 Domena wysyłająca została zablokowana przez usługę WNS. Nie wysyłaj dalszych powiadomień do tego kanału. Domena wysyłająca została zablokowana przez WNS za nadużywanie powiadomień push.
413 Jednostka żądania jest za duża Ładunek powiadomień przekracza limit rozmiaru 5000 bajtów. Zarejestruj szczegóły żądania. Sprawdź ładunek, aby upewnić się, że znajduje się on w ramach ograniczeń rozmiaru.
500 Wewnętrzny błąd serwera Awaria wewnętrzna spowodowała niepowodzenie dostarczania powiadomień. Zarejestruj szczegóły żądania. Zgłoś ten problem za pośrednictwem forów deweloperów.
Usługa 503 jest niedostępna Serwer jest obecnie niedostępny. Zarejestruj szczegóły żądania. Zgłoś ten problem za pośrednictwem forów deweloperów. Jeśli zaobserwujesz nagłówek Retry-After, wyślij swoje żądanie po podaniu wartości nagłówka Retry-After w odpowiedzi.

Nieobsługiwane funkcje HTTP

Interfejs internetowy usługi WNS obsługuje protokół HTTP 1.1, ale nie obsługuje następujących funkcji:

  • Chunking
  • Potokowanie (POST nie jest idempotentne)
  • Mimo że są obsługiwane, deweloperzy powinni wyłączyć funkcję Expect-100, ponieważ wprowadza to opóźnienie podczas wysyłania powiadomienia.
  • Last updated on