Encabezados de respuesta y solicitud del servicio de notificaciones de inserción (aplicaciones de Windows en tiempo de ejecución)

Artículo
12/12/2015

[ Este artículo está destinado a desarrolladores de Windows 8.x y Windows Phone 8.x que escriben aplicaciones de Windows en tiempo de ejecución. Si estás desarrollando para Windows 10, consulta la documentación más reciente

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

Consulta Introducción a los servicios de notificaciones de inserción de Windows (WNS) para ver los conceptos de notificación de inserción y WNS, sus requisitos y su funcionamiento.

Solicitud y recepción de un token de acceso

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

Solicitud de token de acceso

Se envía una solicitud HTTP a WNS para autenticar el servicio de nube y recuperar un token de acceso a cambio. La solicitud se emite al siguiente nombre de dominio completo (FQDN) a través de la Capa de sockets seguros (SSL).

https://login.live.com/accesstoken.srf

Parámetros de solicitud de token de acceso

El servicio de nube envía estos parámetros necesarios en el cuerpo de la solicitud HTTP, con el formato "aplicación/x-www-formato-urlcodificada" . Debes asegurarte de que todos los parámetros estén codificados en URL.

Parámetro	Obligatorio/opcional	Descripción
grant_type	Obligatorio	Se debe establecer en "client_credentials".
client_id	Obligatorio	Identificador de seguridad del paquete (SID) para el servicio de nube que se te asignó al registrar la aplicación en la Tienda Windows.
client_secret	Obligatorio	Clave secreta para el servicio de nube que se te asignó al registrar la aplicación en la Tienda Windows.
scope	Obligatorio	Se debe establecer en: Windows: "notify.windows.com" Windows Phone: "notify.windows.com" o "s.notify.live.net"

Respuesta de token de acceso

WNS autentica el servicio de nube y, si es correcto, responde con "200 Correcto", incluido el token de acceso. De lo contrario, WNS responde con un código de error HTTP correspondiente, tal como se describe en el borrador del protocolo OAuth 2.0.

Parámetros de respuesta de token de acceso

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

Parámetro	Obligatorio/opcional	Descripción
access_token	Obligatorio	El token de acceso que el servicio de nube usará cuando envíe una notificación.
token_type	Opcional	Siempre se devuelve como "portador".

Código de respuesta

Código de respuesta HTTP	Descripción
200 Correcto	La solicitud se realizó correctamente.
400 Solicitud incorrecta	Error en la autenticación. Consulta las Solicitudes de comentarios (RFC) del borrador de OAuth si quieres obtener información sobre los parámetros de respuesta.

Ejemplo

A continuación se muestra un ejemplo de 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"
 }

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 una solicitud de notificación
Enviar una respuesta de notificación
Características HTTP no compatibles

Enviar una solicitud de notificación

Al enviar una solicitud de notificación, la aplicación que llama realiza una solicitud HTTP sobre SSL, dirigida al identificador uniforme de recursos (URI) del canal. "Longitud de contenido" es un encabezado HTTP estándar que se debe especificar en la solicitud. Todos los otros encabezados estándar son opcionales o no compatibles.

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

Parámetros de solicitud

Nombre del encabezado	Obligatorio/opcional	Descripción
Autorización	Obligatorio	Encabezado de autorización HTTP estándar que se usa para autenticar la solicitud de notificación. El servicio de nube proporciona su token de acceso en este encabezado.
Tipo de contenido	Obligatorio	Encabezado de autorización HTTP estándar. Para las notificaciones, notificaciones del sistema y notificaciones de iconos, este encabezado debe establecerse en "text/xml". Para las notificaciones sin procesar, este encabezado debe establecerse en "application/octet-stream".
Longitud de contenido	Obligatorio	Encabezado de autorización HTTP estándar para indicar el tamaño de la carga de la solicitud.
Tipo-X-WNS	Obligatorio	Define el tipo de notificación en la carga: de icono, del sistema, notificación o sin formato.
Directiva-de-memoria-caché-de-X-WNS	Opcional	Habilita o deshabilita el almacenamiento en cache de la notificación. Este encabezado se aplica solo a notificaciones, notificaciones de icono y notificaciones sin procesar.
SolicitudDeEstado-de-X-WNS	Opcional	Solicita el estado del dispositivo y el estado de la conexión WNS en la respuesta de la notificación.
Etiqueta-de-X-WNS	Opcional	Cadena que se usa para proporcionarle una etiqueta de identificación a una notificación, y se usa para iconos compatibles con la cola de notificaciones. Este encabezado se aplica solo a notificaciones de icono.
TTL-de-X-WNS	Opcional	Valor entero, expresado en segundos, que especifica el período de vida (TTL).
X-WNS-SuppressPopup	Opcional	Solo Windows Phone: envía una notificación del sistema directamente al centro de actividades sin generar la propia notificación del sistema.
X-WNS-Group	Opcional	Solo Windows Phone: se utiliza con el encabezado X-WNS-Tag para agrupar notificaciones en el centro de actividades.
X-WNS-Match	Se requiere en función de la situación	Solo Windows Phone: se requiere para identificar el destino o destinos al eliminar una notificación del sistema desde el centro de actividades mediante el método HTTP DELETE.

Notas importantes

Longitud de contenido y tipo de contenido son los únicos encabezados HTTP estándares que se incluyen en la notificación entregada al cliente, independientemente de que se hayan incluido otros encabezados estándares en la solicitud.
Todos los otros encabezados HTTP estándares se omiten o devuelven un error si la funcionalidad no es compatible.

Autorización

El encabezado de autorización se usa para especificar las credenciales de la persona que llama, de acuerdo con el método de autorización OAuth 2.0 para tokens portador.

La sintaxis está compuesta por un "Portador" literal de cadena, seguido de un espacio y del token de acceso. Este token de acceso se recupera al emitir la solicitud de token de acceso descrita antes. El mismo token de acceso se puede usar en solicitudes de notificación subsiguientes hasta que expire.

Este encabezado es obligatorio.

Authorization: Bearer <access-token>

Tipo-X-WNS

Estos son los tipos de notificación compatibles con WNS. Este encabezado indica el tipo de notificación y cómo WNS debería gestionarla. Después de que la notificación haya llegado al cliente, se valida la carga real con el tipo especificado. Este encabezado es obligatorio.

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

Valor	Descripción
wns/badge	Una notificación para crear una notificación superpuesta en el icono. El encabezado Content-Type incluido en la solicitud de notificación debe establecerse en "text/xml".
wns/tile	Una 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/toast	Una notificación para generar una notificación del sistema en el cliente. El encabezado Content-Type incluido en la solicitud de notificación debe establecerse en "text/xml".
wns/raw	Una notificación que puede contener una carga personalizada y que se entrega directamente a la aplicación. El encabezado Content-Type incluido en la solicitud de notificación debe establecerse en "application/octet-stream".

Directiva-de-memoria-caché-de-X-WNS

Cuando el dispositivo de destino de la notificación esté desconectado, WNS almacenará en la memoria caché una notificación y una notificación de icono por aplicación. Si está habilitado el desplazamiento de notificaciones para la aplicación, WNS almacenará en la memoria caché hasta cinco notificaciones de icono. De manera predeterminada, las notificaciones sin procesar no se almacenan en caché, pero si se habilita el almacenamiento en caché de notificaciones sin procesar, se almacenará una de estas notificaciones sin procesar. La memoria caché no retiene los elementos indefinidamente, sino que se descartarán después de un período de tiempo razonable. De lo contrario, el contenido almacenado en la memoria caché se entrega cuando el dispositivo se vuelva a conectar.

Este encabezado es opcional y debería usarse solo en casos donde el servicio de nube quiere invalidar el comportamiento de almacenamiento en caché predeterminado.

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

Valor	Descripción
cache	Predeterminado. Las notificaciones no se almacenarán en caché si el usuario está desconectado. Este es el valor predeterminado para las notificaciones y notificaciones de iconos.
no-cache	La notificación no se almacenará en caché si el usuario está desconectado. Este es el valor predeterminado para las notificaciones sin procesar.

SolicitudDeEstado-de-X-WNS

Especifica si la respuesta debería incluir el estado del dispositivo y el estado de 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 la notificación en la respuesta.
false	Predeterminado. No devuelve el estado del dispositivo y el estado de la notificación.

Etiqueta-de-X-WNS

Asigna una etiqueta tag 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 desplazamiento de las notificaciones. Si ya existe una notificación con esta etiqueta en la cola, una nueva notificación con la misma etiqueta toma su lugar.

Nota Este encabezado es opcional y sólo se usa cuando se envían notificaciones de icono.

Nota En las aplicaciones de la Tienda de Windows Phone, el encabezado X-WNS-Tag puede usarse con el encabezado X-WNS-Group para permitir que se muestren varias notificaciones con la misma etiqueta en el centro de actividades.

X-WNS-Tag: <string value>

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

TTL-de-X-WNS

Especifica el TTL (tiempo de expiración) de una notificación. Esto no suele ser necesario, pero se puede usar si quieres asegurarte de que las notificaciones no se muestren después de un cierto tiempo. El TTL se especifica en segundos y es relativo al momento en que WNS recibe la solicitud. Cuando se especifica un TTL, el dispositivo no mostrará la notificación después de ese tiempo. Ten en cuenta que esto podría provocar que la notificación no se muestre nunca si el TTL es demasiado corto. En general, se medirá el tiempo de expiración al menos en minutos.

Este encabezado es opcional. Si no se especifica ningún valor, la notificación no expira y será reemplazada de acuerdo con el esquema normal de sustitución de notificaciones.

X-WNS-TTL: <integer value>

Valor	Descripción
valor entero	La duración de la notificación, en segundos, después de que WNS recibe la solicitud.

X-WNS-SuppressPopup

Nota En las aplicaciones de la Tienda de Windows Phone, tienes la opción de suprimir la interfaz de usuario de una notificación del sistema en lugar de enviar la notificación directamente al centro de actividades. Esto permite la entrega silenciosa de tu notificación, una opción potencialmente superior para notificaciones menos urgentes. Este encabezado es opcional y solo se utiliza en canales de Windows Phone. Si incluyes este encabezado en un canal de Windows, tu notificación se descartará y recibirás una respuesta de error de WNS.

X-WNS-SuppressPopup: true | false

Valor	Descripción
true	Envía la notificación del sistema directamente al centro de actividades; no generes la UI de la notificación del sistema.
false	Predeterminado. Genera la UI de notificación del sistema y añade 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 varias notificaciones del sistema con la misma etiqueta solo si están etiquetadas como pertenecientes a diferentes grupos. Por ejemplo, imagínate una aplicación de libro de recetas. Cada receta sería identificada mediante una etiqueta. Una notificación del sistema que contenga un comentario sobre esa receta tendría la etiqueta de la receta, pero una etiqueta del grupo de comentarios. Una notificación del sistema que contenga una puntuación sobre esa receta tendría nuevamente la etiqueta de la receta, pero una etiqueta del grupo de puntuaciones. Estas diferentes etiquetas de grupo permiten que ambas notificaciones del sistema se muestren a la vez en el centro de actividades. Este encabezado es opcional.

X-WNS-Group: <string value>

Valor	Descripción
valor de cadena	Una 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 del sistema determinada, un conjunto de notificaciones del sistema (mediante etiqueta o grupo) o todas las notificaciones del sistema 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 se requiere en una solicitud de notificación HTTP DELETE. Cualquier carga incluida con esta solicitud de notificación se ignora.

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
tipo:wns/notificación del sistema;grupo=<valor de cadena>;etiqueta=<valor de cadena>	Elimina una notificación individual etiquetada con la etiqueta y el grupo especificado.
tipo:wns/notificación del sistema;grupo=<valor de cadena>	Elimina todas las notificaciones etiquetadas con el grupo especificado.
tipo:wns/notificación del sistema;etiqueta=<valor de cadena>	Elimina todas las notificaciones etiquetadas con la etiqueta especificada.
tipo:wns/notificación del sistema;todas	Borra todas las notificaciones de tu aplicación del centro de actividades.

Enviar una respuesta de notificación

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

Parámetros de la respuesta

Nombre del encabezado	Obligatorio/opcional	Descripción
Seguimiento-de-depuración-de-X-WNS	Opcional	Información sobre depuración que debe registrarse para ayudar a solucionar problemas cuando estos se informan.
EstadoDeConexiónDelDispositivo-de-X-WNS	Opcional	El estado del dispositivo, que se devuelve solo si se pide en la solicitud de notificación a través del encabezado EstadoDeConexiónDelDispositivo-de-X-WNS.
Descripción-del-error-de-X-WNS	Opcional	Una cadena de error legible para el ojo humano que debe registrarse para ayudar en la depuración.
Id.-de-mensaje-de-X-WNS	Opcional	Un único identificador para la notificación, que se usa para fines de depuración. Al informar de un problema, esta información debe registrarse para ayudar a solucionarlo.
X-WNS-Status	Opcional	Indica si WNS recibió y procesó la notificación correctamente. Al informar de un problema, esta información debe registrarse para ayudar a solucionarlo.

Seguimiento-de-depuración-de-X-WNS

Este encabezado devuelve información útil sobre depuración como una cadena. Se recomienda que el encabezado esté registrado para ayudar a los desarrolladores a depurar problemas. Este encabezado, junto con el encabezado Id.-de-mensaje-de-X-WNS, es obligatorio al informar un problema a WNS.

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

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

EstadoDeConexiónDelDispositivo-de-X-WNS

Este encabezado devuelve el estado del dispositivo a la aplicación que llama, si se solicita en el encabezado SolicitudDeEstado-de-X-WNS 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.
disconnected	El dispositivo no está en línea y no está conectado a WNS.
tempconnected	El dispositivo perdió la conexión a WNS temporalmente, por ejemplo cuando se pierde una conexión 3G o se modifica el interruptor inalámbrico de un equipo portátil. La Plataforma del cliente de notificación la considera como una interrupción temporal y no como una desconexión intencional.

Descripción-del-error-de-X-WNS

Este encabezado proporciona una cadena de error legible para el ojo humano que debe registrarse para ayudar en la depuración.

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

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

Id.-de-mensaje-de-X-WNS

Se usa este encabezado para proporcionarle a la persona que llama un identificador para la notificación. Se recomienda que el encabezado esté registrado para ayudar a depurar problemas. Este encabezado, junto con el encabezado de Seguimiento-de-depuración-de-X-WNS, es obligatorio al informar un problema a WNS.

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

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

X-WNS-Status

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

X-WNS-Status: received | dropped | channelthrottled

Valor	Descripción
received	WNS recibió y procesó la notificación. Nota Esto no garantiza que el dispositivo haya recibido la notificación.
dropped	La notificación se descartó explícitamente debido a un error o porque el cliente ha rechazado estas notificaciones explícitamente. También se descartarán las notificaciones del sistema si el dispositivo está desconectado.
channelthrottled	La notificación se descartó porque el servidor de la aplicación superó el límite de velocidad para este canal específico.

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 a usar en la depuración. Cuando los desarrolladores informan un problema a WNS, deben proporcionar códigos de respuesta e información sobre el encabezado.

Código de respuesta HTTP	Descripción	Acción recomendada
200 Correcto	WNS aceptó la notificación.	Ninguno requerido.
400 Solicitud incorrecta	Uno o más encabezados no se especificaron correctamente o causan conflicto con otro encabezado.	Registra los detalles de la solicitud. Inspecciona la solicitud y compara con esta documentación.
401 No autorizado	El servicio de nube no presentó un vale de autenticación válido. El vale de OAuth puede no ser válido.	Solicita un token de acceso válido mediante la autenticación del servicio de nube con la solicitud de token de acceso.
403 Prohibido	El servicio de nube no está autorizado para enviar una notificación a este URI a pesar de estar autenticadas.	El token de acceso proporcionado en la solicitud no coincide con las credenciales de la aplicación que solicitó el URI de canal. Asegúrate de que el nombre del paquete en el manifiesto de la aplicación coincida con las credenciales del servicio de nube proporcionadas a la aplicación en el panel.
404 No se encuentra	El URI de canal no es válido o no está reconocido por WNS.	Registra los detalles de la solicitud. No envíes más notificaciones a este canal porque las notificaciones dirigidas a esta dirección producirán errores.
405 Método no permitido	Método inválido (GET, CREATE); solo se permite POST (Windows o Windows Phone) o DELETE (solo Windows Phone).	Registra los detalles de la solicitud. Cambia al uso de HTTP POST.
406 No aceptable	El servicio de nube superó su límite.	Registra los detalles de la solicitud. Reduce la velocidad a la cual estás enviando notificaciones.
410 Ya no existe	El canal expiró.	Registra los detalles de la solicitud. No envíes más notificaciones a este canal. Haz que la aplicación solicite un nuevo URI de canal.
413 Entidad de solicitud demasiado grande	La carga de la notificación supera el límite de tamaño de 5000 bytes.	Registra los detalles de la solicitud. Inspecciona la carga para asegurarte de que esté dentro de los límites de tamaño.
500 Error interno del servidor	Un error interno provocó un error en la entrega de las notificaciones.	Registra los detalles de la solicitud. Envía un informe sobre este problema a través de los foros de desarrolladores.
503 Servicio no disponible	El servidor no está actualmente disponible.	Registra los detalles de la solicitud. Envía un informe sobre este problema a través de los foros de desarrolladores.

Para obtener información detallada de solución de problemas relacionados con códigos de respuesta concretos, consulta Solución de problemas de notificaciones de icono, del sistema y de distintivo. Consulta también COM Error Codes (WPN, MBN, P2P, Bluetooth).

Características HTTP no compatibles

La interfaz web WNS es compatible con HTTP 1.1 pero no admite las siguientes características:

Fragmentación
Canalización (POST no es idempotent)
A pesar de que es compatible, los desarrolladores deberían deshabilitar Expect-100 ya que provoca latencia al enviar una notificación.

Temas relacionados

Inicio rápido: envío de una notificación de inserción

Instrucciones y lista de comprobación de notificaciones de inserción

Cómo autenticar con los Servicios de notificaciones de inserción de Windows (WNS)

Cómo solicitar, crear y guardar un canal de notificaciones

Ejemplo de notificaciones de inserción y periódicas

Introducción a WNS