Encabezados de solicitud y respuesta del servicio de notificaciones push (aplicaciones de Windows Runtime)

En este tema se describen las API web de servicio a servicio y los protocolos necesarios para enviar una notificación push.

Consulta el resumen de los Servicios de notificaciones push de Windows (WNS) para un análisis conceptual de los conceptos, requisitos y operación de las notificaciones push y de WNS.

Solicitud y recepción de un token de acceso

En esta sección se describen los parámetros de solicitud y respuesta implicados al autenticarse con WNS.

Solicitud de token de acceso

Se envía una solicitud HTTP a WNS para autenticar el servicio en la nube y recuperar un token de acceso a cambio. La solicitud se emite para https://login.live.com/accesstoken.srf mediante capa de sockets seguros (SSL).

Parámetros de solicitud de token de acceso

El servicio en la nube envía estos parámetros necesarios en el cuerpo de la solicitud HTTP mediante el formato "application/x-www-form-urlencoded". Debe asegurarse de que todos los parámetros están codificados en dirección URL.

Parámetro	Obligatorio	Descripción
tipo_de_subvención	VERDADERO	Debe establecerse en client_credentials.
ID de cliente	VERDADERO	Identificador de seguridad del paquete (SID) para el servicio en la nube tal como se asigna al registrar la aplicación con Microsoft Store.
secreto_del_cliente	VERDADERO	Clave secreta para el servicio en la nube tal como se asigna al registrar la aplicación con Microsoft Store.
alcance	VERDADERO	Se debe establecer en notify.windows.com

Respuesta de token de acceso

WNS autentica el servicio en la nube y, si tiene éxito, responde con un "200 OK", incluyendo el token de acceso. De lo contrario, WNS responde con un código de error HTTP adecuado, tal como se describe en el borrador del protocolo OAuth 2.0.

Parámetros de respuesta del token de acceso

Se devuelve un token de acceso en la respuesta HTTP si el servicio en la nube se ha autenticado correctamente. Este token de acceso se puede usar en las solicitudes de notificación hasta que expire. La respuesta HTTP usa el tipo de medio "application/json".

Parámetro	Obligatorio	Descripción
token de acceso	VERDADERO	Token de acceso que usará el servicio en la nube cuando envíe una notificación.
tipo_de_token	FALSO	Siempre se devuelve como bearer.

Código de respuesta

Código de respuesta HTTP	Descripción
200 Ok	La solicitud fue exitosa.
400 Solicitud incorrecta	Error de autenticación. Vea el borrador de OAuth Solicitud de comentarios (RFC) para los parámetros de respuesta.

Ejemplo

A continuación se muestra un ejemplo de una respuesta de autenticación correcta:

 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
 }

Envío de una solicitud de notificación y recepción de una respuesta

En esta sección se describen los encabezados implicados en una solicitud HTTP a WNS para entregar una notificación y los implicados en la respuesta.

• Enviar solicitud de notificación
• Enviar respuesta de notificación
• Características HTTP no admitidas

Enviar solicitud de notificación

Al enviar una solicitud de notificación, la aplicación que realiza la llamada realiza una solicitud HTTP a través de SSL, dirigida al identificador uniforme de recursos (URI) del canal. "Content-Length" es un encabezado HTTP estándar que se debe especificar en la solicitud. Todos los demás encabezados estándar son opcionales o no son compatibles.

Además, los encabezados de solicitud personalizados que se enumeran aquí se pueden usar en la solicitud de notificación. Algunos encabezados son necesarios, mientras que otros son opcionales.

Parámetros de solicitud

Nombre del encabezado	Obligatorio	Descripción
Autorización	VERDADERO	Encabezado de autorización HTTP estándar que se usa para autenticar la solicitud de notificación. El servicio en la nube proporciona su token de acceso en este encabezado.
Tipo de contenido	VERDADERO	Encabezado de autorización HTTP estándar. En el caso de las notificaciones del sistema, el icono y el distintivo, este encabezado debe establecerse en text/xml. Para las notificaciones sin formato, este encabezado debe establecerse en application/octet-stream.
Longitud del contenido	VERDADERO	Encabezado de autorización HTTP estándar para indicar el tamaño de la carga de la solicitud.
X-WNS-Type	VERDADERO	Define el tipo de notificación en la carga útil: mosaico, notificación emergente, distintivo o crudo.
X-WNS:Cache-Policy	FALSO	Habilita o deshabilita el almacenamiento en caché de notificaciones. Este encabezado solo se aplica a las notificaciones de icono, distintivo y sin formato.
X-WNS-RequestForStatus	FALSO	Solicita el estado del dispositivo y el estado de conexión de WNS en la respuesta de notificación.
X-WNS-Tag	FALSO	Cadena utilizada para proporcionar una notificación con una etiqueta de identificación, que se usa para los módulos que admiten la cola de notificaciones. Este encabezado solo se aplica a las notificaciones de icono.
X-WNS-TTL	FALSO	Valor entero, expresado en segundos, que especifica el período de vida (TTL).
MS-CV	FALSO	Valor del vector de correlación utilizado para su solicitud.

Notas importantes

• Content-Length y Content-Type son los únicos encabezados HTTP estándar que se incluyen en la notificación que se entrega al cliente, independientemente de si se han incluido otros encabezados estándar en la solicitud.
• Todos los demás encabezados HTTP estándar se omiten o devuelven un error si no se admite la funcionalidad.
• A partir de febrero de 2023, WNS almacenará en caché solo una notificación de icono cuando el dispositivo esté sin conexión.

Autorización

El encabezado de autorización se usa para especificar las credenciales de la entidad que realiza la llamada, siguiendo el método de autorización de OAuth 2.0 para tokens de portador.

La sintaxis consta de un literal de cadena "Bearer", seguido de un espacio, seguido del token de acceso. Este token de acceso se recupera mediante la emisión de la solicitud de token de acceso descrita anteriormente. El mismo token de acceso se puede usar en las solicitudes de notificación posteriores hasta que expire.

Este encabezado es obligatorio.

Authorization: Bearer <access-token>

X-WNS-Type

Estos son los tipos de notificación admitidos por WNS. Este encabezado indica el tipo de notificación y cómo WNS debe controlarlo. Una vez que la notificación llega al cliente, la carga real se valida con este tipo especificado. Este encabezado es obligatorio.

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

Importancia	Descripción
wns/insignia	Notificación para crear una superposición de distintivo en el icono. El encabezado Content-Type incluido en la solicitud de notificación debe establecerse en text/xml.
wns/mosaico	Notificación para actualizar el contenido del icono. El encabezado Content-Type incluido en la solicitud de notificación debe establecerse en text/xml.
wns/tostadas	Notificación para proponer un brindis en el cliente. El encabezado Content-Type incluido en la solicitud de notificación debe establecerse en text/xml.
wns/crudo	Notificación que puede contener una carga personalizada y se entrega directamente a la aplicación. El encabezado Content-Type incluido en la solicitud de notificación debe establecerse en application/octet-stream.

X-WNS:Cache-Policy

Cuando el dispositivo de destino de notificación está sin conexión, WNS almacenará en caché un distintivo, una tesela y una notificación de brindis para cada URI del canal. De forma predeterminada, las notificaciones sin procesar no se almacenan en caché, pero si el almacenamiento en caché de notificaciones sin procesar está habilitado, se almacena en caché una notificación sin procesar. Los elementos no se mantienen en la memoria caché indefinidamente y se quitarán después de un período de tiempo razonable. De lo contrario, el contenido almacenado en caché se entrega cuando el dispositivo se conecta a continuación.

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

Importancia	Descripción
caché	Predeterminado. Las notificaciones se almacenarán en caché si el usuario está sin conexión. Esta es la configuración predeterminada para las notificaciones de icono y distintivo.
sin caché	La notificación no se almacenará en caché si el usuario está sin conexión. Esta es la configuración predeterminada para las notificaciones sin procesar.

X-WNS-RequestForStatus

Especifica si la respuesta debe incluir el estado del dispositivo y el estado de conexión de WNS. Este encabezado es opcional.

    X-WNS-RequestForStatus: true | false

Importancia	Descripción
cierto	Devuelve el estado del dispositivo y el estado de notificación en la respuesta.
falso	Predeterminado. No devuelva el estado del dispositivo y el estado de notificación.

X-WNS-Tag

Asigna una etiqueta a una notificación. La etiqueta se usa en la directiva de reemplazo del icono en la cola de notificaciones cuando la aplicación ha optado por el ciclo de notificación. Si ya existe una notificación con esta etiqueta en la cola, se realiza una nueva notificación con la misma etiqueta.

Nota:

Este encabezado es opcional y solo se usa al enviar notificaciones de icono.

    X-WNS-Tag: <string value>

Importancia	Descripción
valor de cadena	Cadena alfanumérica de no más de 16 caracteres.

X-WNS-TTL

Especifica el TTL (hora de expiración) de una notificación. Esto no suele ser necesario, pero se puede usar si desea asegurarse de que las notificaciones no se muestran más adelante de un tiempo determinado. El TTL se especifica en segundos y es relativo al tiempo que WNS recibe la solicitud. Cuando se especifica un TTL, el dispositivo no mostrará la notificación después de ese tiempo. Tenga en cuenta que esto podría dar lugar a que la notificación nunca se muestre en absoluto si el TTL es demasiado corto. En general, se medirá un tiempo de expiración en al menos minutos.

Este encabezado es opcional. Si no se especifica ningún valor, la notificación no expira y se reemplazará en el esquema de reemplazo de notificaciones normal.

X-WNS-TTL: <integer value>

Importancia	Descripción
valor entero	El período de vida de la notificación, en segundos, después de que WNS reciba la solicitud.

X-WNS-SuppressPopup

Nota:

En el caso de las aplicaciones de la Tienda de Windows Phone, tienes la opción de suprimir la interfaz de una notificación de tipo 'toast', enviándola directamente al centro de actividades en su lugar. Esto permite que la notificación se entregue silenciosamente, una opción potencialmente superior para las notificaciones menos urgentes. Este encabezado es opcional y solo se usa en canales de Windows Phone. Si incluye este encabezado en un canal de Windows, la notificación será eliminada y recibirá una respuesta con error de WNS.

X-WNS-SuppressPopup: verdadero | falso

Importancia	Descripción
cierto	Envíe la notificación toast directamente al centro de notificaciones; no genere la interfaz de usuario de toast.
falso	Predeterminado. Genere la interfaz de usuario del sistema y agregue la notificación al centro de actividades.

X-WNS-Group

Nota:

El centro de acción para las aplicaciones de la Tienda de Windows Phone puede mostrar varias notificaciones emergentes con la misma etiqueta solo si se etiquetan como pertenecientes a grupos diferentes. Por ejemplo, considere una aplicación de libro de recetas. Cada receta se identificaría mediante una etiqueta. Un aviso que contiene un comentario sobre esa receta tendría la etiqueta de la receta, pero pertenecería a la categoría de grupo de comentarios. Un mensaje emergente que contiene una calificación para esa receta volvería a tener la etiqueta de esa receta, pero tendría una etiqueta de grupo de calificación. Esas etiquetas de grupo diferentes permitirían que ambas notificaciones del sistema se muestren a la vez en el centro de actividades. Este encabezado es opcional.

Grupo X-WNS: <string value>

Importancia	Descripción
valor de cadena	Cadena alfanumérica de no más de 16 caracteres.

X-WNS-Match

Nota:

Se usa con el método HTTP DELETE para quitar una notificación emergente específica, un conjunto de notificaciones emergentes (por etiqueta o grupo) o todas las notificaciones emergentes del centro de actividades para aplicaciones de la Tienda de Windows Phone. Este encabezado puede especificar un grupo, una etiqueta o ambos. Este encabezado es necesario en una solicitud de notificación HTTP DELETE. Se omite cualquier carga incluida con esta solicitud de notificación.

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

Importancia	Descripción
type:wns/toast; group=<string value>; tag=<string value>	Quite una sola notificación etiquetada con la etiqueta y el grupo especificados.
type:wns/toast; group=<string value>	Quite todas las notificaciones etiquetadas con el grupo especificado.
tipo:wns/toast; etiqueta=<string value>	Quite todas las notificaciones etiquetadas con la etiqueta especificada.
type:wns/toast; todo	Borre todas las notificaciones de la aplicación desde el centro de actividades.

Enviar respuesta de notificación

Una vez que WNS procesa la solicitud de notificación, envía un mensaje HTTP en respuesta. En esta sección se describen los parámetros y encabezados que se pueden encontrar en esa respuesta.

Parámetros de respuesta

Nombre del encabezado	Obligatorio	Descripción
X-WNS:Debug-Trace	FALSO	Información de depuración que se debe registrar para ayudar en la resolución de problemas al informarlos.
X-WNS-DeviceConnectionStatus	FALSO	El estado del dispositivo se devuelve solo si se solicita en la solicitud de notificación a través del encabezado X-WNS-RequestForStatus.
X-WNS:Error-Description	FALSO	Un mensaje de error legible para humanos que se debe registrar para ayudar con la depuración.
X-WNS:Msg-ID	FALSO	Un identificador único para la notificación, utilizado para propósitos de depuración. Al notificar un problema, esta información se debe registrar para ayudar en la solución de problemas.
X-WNS-Status	FALSO	Indica si WNS recibió y procesó correctamente la notificación. Al notificar un problema, esta información se debe registrar para ayudar en la solución de problemas.
MS-CV	FALSO	Información de depuración que se debe registrar para ayudar en la resolución de problemas al informarlos.

X-WNS:Debug-Trace

Este encabezado devuelve información útil de depuración como una cadena. Se recomienda que este encabezado se registre para ayudar a los desarrolladores a depurar problemas. Este encabezado, junto con el encabezado X-WNS-Msg-ID y MS-CV, son necesarios al notificar un problema a WNS.

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

Importancia	Descripción
valor de cadena	Cadena alfanumérica.

X-WNS-DeviceConnectionStatus

Este encabezado devuelve el estado del dispositivo a la aplicación que realiza la llamada, si se solicita en el encabezado X-WNS-RequestForStatus de la solicitud de notificación.

X-WNS-DeviceConnectionStatus: conectado | desconectado | desconectado temporalmente

Importancia	Descripción
conectado	El dispositivo está en línea y conectado a WNS.
desconectado	El dispositivo está sin conexión y no está conectado a WNS.
tempconnected (en desuso)	El dispositivo perdió temporalmente la conexión a WNS, por ejemplo, cuando se pierde una conexión 3G o se activa el interruptor inalámbrico en un portátil. La Plataforma cliente de notificaciones la ve como una interrupción temporal en lugar de una desconexión intencionada.

X-WNS:Error-Description

Este encabezado proporciona una cadena de error legible que se debe registrar para ayudar con la depuración.

X-WNS-error-description: <string value>

Importancia	Descripción
valor de cadena	Cadena alfanumérica.

X-WNS:Msg-ID

Este encabezado se usa para proporcionar al autor de la llamada un identificador para la notificación. Se recomienda registrar este encabezado para ayudar a depurar problemas. Este encabezado, junto con elDebug-Trace X-WNS y MS-CV, son necesarios al notificar un problema a WNS.

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

Importancia	Descripción
valor de cadena	Cadena alfanumérica de no más de 16 caracteres.

X-WNS-Status

Este encabezado describe cómo WNS controló la solicitud de notificación. Esto se puede usar en lugar de interpretar los códigos de respuesta como correctos o erróneos.

X-WNS-Status: recibido | descartado | canal limitado

Importancia	Descripción
recibido	WNS recibió y procesó la notificación. Nota: Esto no garantiza que el dispositivo reciba la notificación.
Cayó	La notificación se quitó explícitamente debido a un error o porque el cliente ha rechazado explícitamente estas notificaciones. Las notificaciones de toast también se descartarán si el dispositivo está desconectado.
canal limitado	La notificación se quitó porque el servidor de aplicaciones superó el límite de velocidad de este canal específico.

MS-CV

Este encabezado proporciona un vector de correlación relacionado con la solicitud que se usa principalmente para la depuración. Si se proporciona un CV como parte de la solicitud, WNS usará este valor; de lo contrario, WNS generará y responderá con un CV. Este encabezado, junto con el encabezado X-WNS-Debug-Trace y X-WNS-Msg-ID, son necesarios al notificar un problema a WNS.

Importante

Genera un nuevo CV para cada solicitud de notificación push si proporcionas tu propio CV.

MS-CV: <string value>

Importancia	Descripción
valor de cadena	Sigue el estándar de vector de correlación

Códigos de respuesta

Cada mensaje HTTP contiene uno de estos códigos de respuesta. WNS recomienda que los desarrolladores registren el código de respuesta para su uso en la depuración. Cuando los desarrolladores notifican un problema a WNS, deben proporcionar códigos de respuesta e información de encabezado.

Código de respuesta HTTP	Descripción	Acción recomendada
200 Ok	WNS aceptó la notificación.	No es necesario.
400 Solicitud incorrecta	Uno o varios encabezados se especificaron incorrectamente o entraron en conflicto con otro encabezado.	Registre los detalles de la solicitud. Inspeccione la solicitud y compárelo con esta documentación.
401 No autorizado	El servicio en la nube no presentó un vale de autenticación válido. El vale de OAuth puede no ser válido.	Solicite un token de acceso válido mediante la autenticación del servicio en la nube mediante la solicitud de token de acceso.
403 Prohibido	El servicio en la nube no está autorizado para enviar una notificación a este URI aunque estén autenticados.	El token de acceso proporcionado en la solicitud no coincide con las credenciales de la aplicación que solicitó el URI del canal. Asegúrese de que el nombre del paquete en el manifiesto de la aplicación coincide con las credenciales del servicio en la nube que se proporcionan a la aplicación en el panel.
404 No encontrado	La URI del canal no es válida o no está reconocida por WNS.	Registre los detalles de la solicitud. No envíe más notificaciones a este canal; Se producirá un error en las notificaciones a esta dirección.
Método 405 no permitido	Método no válido (GET, CREATE); solo se permite POST (Windows o Windows Phone) o DELETE (solo Windows Phone).	Registre los detalles de la solicitud. Cambie a usar HTTP POST.
406 No aceptable	El servicio en la nube superó su límite.	Por favor, envíe su solicitud después del valor del encabezado Retry-After en la respuesta.
410 Desaparecido	El canal expiró.	Registre los detalles de la solicitud. No envíe más notificaciones a este canal. Haga que la aplicación solicite un nuevo URI de canal.
410 Dominio bloqueado	WNS ha bloqueado el dominio de envío.	No envíe más notificaciones a este canal. WNS ha bloqueado el dominio de envío por abusar de las notificaciones push.
413 Entidad de solicitud demasiado grande	La carga de notificación supera el límite de tamaño de 5000 bytes.	Registre los detalles de la solicitud. Inspeccione la carga para asegurarse de que se encuentra dentro de las limitaciones de tamaño.
Error interno del servidor 500	Un error interno provocó un error en la entrega de notificaciones.	Registre los detalles de la solicitud. Notifique este problema a través de los foros para desarrolladores.
503 Servicio no disponible	El servidor no está disponible actualmente.	Registre los detalles de la solicitud. Notifique este problema a través de los foros para desarrolladores. Si observa el encabezado Retry-After, envíe su solicitud después del valor del encabezado Retry-After en la respuesta.

Características HTTP no admitidas

La interfaz web WNS admite HTTP 1.1, pero no admite las siguientes características:

• Chunking
• Canalización (POST no es idempotente)
• Aunque se admite, los desarrolladores deben deshabilitar Expect-100, ya que esto introduce latencia al enviar una notificación.