Encabezados de respuesta y solicitud de servicio de notificaciones de inserción (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.

Consulte la información general sobre los Servicios de notificaciones de inserción de Windows (WNS) para obtener una explicación conceptual de los conceptos, requisitos y operaciones de WNS y las notificaciones de inserción.

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 de vuelta. 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". Se debe asegurar de que todos los parámetros estén codificados en la dirección URL.

Parámetro	Obligatorio	Descripción
grant_type	VERDADERO	Se debe establecer en client_credentials.
client_id	VERDADERO	Identificador de seguridad del paquete (SID) para el servicio en la nube como se asignó al registrar la aplicación con Microsoft Store.
client_secret	VERDADERO	Clave secreta para el servicio en la nube como se asignó al registrar la aplicación con Microsoft Store.
scope	VERDADERO	Se debe establecer en notify.windows.com

Respuesta de token de acceso

WNS autentica el servicio en la nube y, si se ejecuta correctamente, responde con un "200 OK", incluyendo el token de acceso. De lo contrario, WNS responde con un código de error HTTP adecuado, tal y 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 autenticó 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
access_token	VERDADERO	Token de acceso que usará el servicio en la nube cuando envíe una notificación.
token_type	FALSO	Siempre se devuelve como bearer.

Response code

Código de respuesta HTTP	Descripción
200 OK	La solicitud fue correcta.
400 Solicitud incorrecta	Error de autenticación. Consulte la Solicitud para comentarios (RFC) Borrador de OAuth para ver 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 la 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 aquellos 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 se admiten.

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

Parámetros de solicitud

Nombre de 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. Para notificaciones de mensajes emergentes, iconos y distintivos, este encabezado debe establecerse en text/xml. Para notificaciones sin procesar, este encabezado debe establecerse en application/octet-stream.
Content-Length	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: de icono, mensaje emergente, distintivo o sin formato.
X-WNS-Cache-Policy	FALSO	Habilita o deshabilita el almacenamiento en caché de notificaciones. Este encabezado solo se aplica a las notificaciones de icono, de distintivo y sin procesar.
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 usada para proporcionar una notificación con una etiqueta de identificación, utilizada para iconos 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 usado para la solicitud.

Notas importantes

• Content-Length y Content-Type son los únicos encabezados HTTP estándar que se incluyen en la notificación entregada al cliente, independientemente de que se hayan 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 solo copiará en caché 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 OAuth 2.0 para los tokens portadores.

La sintaxis consta de un literal de cadena "Bearer", seguido de un espacio y 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 necesario.

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 debería controlarlo WNS. Una vez que la notificación llegue al cliente, la carga real se validará con este tipo especificado. Este encabezado es necesario.

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

Valor	Descripción
wns/badge	Notificación para crear una superposición de distintivo en el icono. El encabezado Content-Type incluido en la solicitud de notificación se debe establecer en text/xml.
wns/tile	Notificación para actualizar el contenido del icono. El encabezado Content-Type incluido en la solicitud de notificación se debe establecer en text/xml.
wns/toast	Notificación para generar un mensaje emergente en el cliente. El encabezado Content-Type incluido en la solicitud de notificación se debe establecer en text/xml.
wns/raw	Notificación que puede contener una carga personalizada y que se envía directamente a la aplicación. El encabezado Content-Type incluido en la solicitud de notificación se debe establecer en application/octet-stream.

X-WNS-Cache-Policy

Cuando el dispositivo de destino de la notificación esté sin conexión, WNS almacenará en caché un distintivo, un icono y un mensaje emergente por cada URI del canal. De manera predeterminada, las notificaciones sin procesar no se almacenan en caché, pero si el almacenamiento en caché de notificaciones sin procesar estuviera habilitado, se almacenará 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 entregará cuando el dispositivo se conecte la próxima vez.

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

Valor	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á desconectado. Esta es la configuración predeterminada para las notificaciones sin procesar.

X-WNS-RequestForStatus

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

    X-WNS-RequestForStatus: true | false

Valor	Descripción
true	Devuelve el estado del dispositivo y el estado de notificación en la respuesta.
false	Predeterminada. No devolver 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 de la cola de notificaciones cuando la aplicación ha optado por el ciclo de notificaciones. Si ya existiera una notificación con esta etiqueta en la cola, tendrá lugar 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>

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

X-WNS-TTL

Especifica el TTL (tiempo 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 muestren después de un tiempo determinado. El TTL se especifica en segundos y es relativo al momento en que WNS recibe la solicitud. Cuando se especifique 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 fuera 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 notificación normal.

X-WNS-TTL: <integer value>

Valor	Descripción
valor entero	Período de vida de la notificación, en segundos, después de que WNS recibe la solicitud.

X-WNS-SuppressPopup

Nota:

Para las aplicaciones de la tienda de Windows Phone, existe la opción de suprimir la interfaz de usuario de los mensajes emergentes, en lugar de enviar la notificación directamente al centro de actividades. 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, se quitará la notificación y recibirá una respuesta de error de WNS.

X-WNS-SuppressPopup: true | false

Valor	Descripción
true	Enviar el mensaje emergente directamente al centro de actividades. No generar la interfaz de usuario del mensaje emergente.
false	Predeterminada. Generar la interfaz de usuario del mensaje emergente, así como agregar la notificación al centro de actividades.

X-WNS-Group

Nota:

El centro de actividades para las aplicaciones de la tienda de Windows Phone puede mostrar varios mensajes 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 mensaje emergente que contenga un comentario sobre esa receta tendría la etiqueta de la receta, pero una etiqueta de grupo de comentarios. Un mensaje emergente que contenga una clasificación de esa receta tendría de nuevo la etiqueta de esa receta, pero tendría una etiqueta de grupo de clasificación. Esas diferentes etiquetas de grupo permitirían que ambos mensajes emergentes se mostrasen a la vez en el centro de actividades. Este encabezado es opcional.

X-WNS-Group: <string value>

Valor	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 un mensaje emergente específico, un conjunto de mensajes emergentes (por etiqueta o grupo) o todos los mensajes emergentes del centro de actividades para las 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 que se incluya 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

Valor	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.
type:wns/toast;tag=<string value>	Quite todas las notificaciones etiquetadas con la etiqueta especificada.
type:wns/toast;all	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 como respuesta. En esta sección se describen los parámetros y encabezados que se pueden encontrar en esa respuesta.

Parámetros de respuesta

Nombre de encabezado	Obligatorio	Descripción
X-WNS-Debug-Trace	FALSO	Información de depuración que se debería registrar para ayudar a solucionar problemas al notificar incidencias.
X-WNS-DeviceConnectionStatus	FALSO	El estado del dispositivo, solo se devuelve si se solicita en la solicitud de notificación a través del encabezado X-WNS-RequestForStatus.
X-WNS-Error-Description	FALSO	Cadena de error legible que se debería registrar para ayudar con la depuración.
X-WNS-Msg-ID	FALSO	Identificador único para la notificación que se usa con fines de depuración. Al informar sobre un problema, esta información se debería registrar para ayudar a solucionarlo.
X-WNS-Status	FALSO	Indica si WNS recibió y procesó correctamente la notificación. Al informar sobre un problema, esta información se debería registrar para ayudar a solucionarlo.
MS-CV	FALSO	Información de depuración que se debería registrar para ayudar a solucionar problemas al notificarlos.

X-WNS-Debug-Trace

Este encabezado devuelve información útil de depuración como una cadena. Se recomienda registrar este encabezado 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>

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

X-WNS-DeviceConnectionStatus

Este encabezado devolverá el estado del dispositivo a la aplicación que realice la llamada en caso de que se solicite en el encabezado X-WNS-RequestForStatus de la solicitud de notificación.

X-WNS-DeviceConnectionStatus: connected | disconnected | tempdisconnected

Valor	Descripción
connected	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 con WNS como, por ejemplo, cuando se pierde una conexión 3G o se inicia el conmutador 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 debería registrar para ayudar con la depuración.

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

Valor	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 el encabezado X-WNS-Debug-Trace y MS-CV, son necesarios al notificar un problema a WNS.

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

Valor	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 incorrectos.

X-WNS-Status: received | dropped | channelthrottled

Valor	Descripción
recibidos	WNS recibió y procesó la notificación. Nota: esto no garantiza que el dispositivo reciba la notificación.
dropped	La notificación se perdió explícitamente debido a un error o porque el cliente rechazó explícitamente estas notificaciones. Los mensajes emergentes también se perderán si el dispositivo está sin conexión.
channelthrottled	La notificación se perdió 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

Genere un nuevo CV para cada solicitud de notificación de inserción si proporciona su propio CV.

MS-CV: <string value>

Valor	Descripción
valor de cadena	Sigue el estándar del 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 informan de un problema a WNS, se necesitan para 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 se requiere ninguna.
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árela con esta documentación.
401 No autorizado	El servicio en la nube no presenta un vale de autenticación válido. El vale de OAuth podría 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 Prohibida	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 del manifiesto de la aplicación coincida con las credenciales del servicio en la nube que se proporcionan a la aplicación en el panel.
404 No encontrado	WNS no reconoce el URI del canal o no es válido.	Registre los detalles de la solicitud. No envíe más notificaciones a este canal. Se producirá un error al notificar a esta dirección.
405 Método no permitido	Método no válido (GET, CREATE): solo se permiten POST (Windows o Windows Phone) o DELETE (solo Windows Phone).	Registre los detalles de la solicitud. Cambie al uso de HTTP POST.
406 No aceptable	El servicio en la nube superó su límite.	Envíe la solicitud después del valor del encabezado Retry-After en la respuesta
410 Ya no existe	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 bloqueó el dominio de envío.	No envíe más notificaciones a este canal. WNS bloqueó el dominio de envío para abusar de las notificaciones de inserción.
413 Entidad de solicitud demasiado larga	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 encuentre dentro de las limitaciones de tamaño.
500 Error interno del servidor	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 se observa el encabezado Retry-After, envíe la solicitud después del valor del encabezado Retry-After en la respuesta.

Características HTTP no admitidas

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

• Fragmentación
• Canalización (POST no es idempotente)
• Aunque se admita, los desarrolladores deberían deshabilitar Expect-100, ya que presenta latencia al enviar notificaciones.