Crear suscripciónCreate subscription

Suscribe una aplicación de escucha para que reciba notificaciones cuando se realiza el tipo de cambios solicitado en el recurso especificado de Microsoft Graph.Subscribes a listener application to receive notifications when the requested type of changes occur to the specified resource in Microsoft Graph.

PermisosPermissions

Para crear una suscripción es necesario un ámbito de lectura para el recurso.Creating a subscription requires read scope to the resource. Por ejemplo, para obtener notificaciones de mensajes, la aplicación necesita el permiso Mail.Read.For example, to get notifications on messages, your app needs the Mail.Read permission.

Según el recurso y el tipo de permisos (delegado o de aplicación) solicitado, el permiso especificado en la tabla siguiente es el menos privilegiado necesario para llamar a esta API.Depending on the resource and the permission type (delegated or application) requested, the permission specified in the following table is the least privileged required to call this API. Para obtener más información, incluido cómo elegir permisos, vea Permisos.To learn more, including how to choose permissions, see Permissions.

Recurso admitidoSupported resource Delegado (cuenta profesional o educativa)Delegated (work or school account) Delegado (cuenta de Microsoft personal)Delegated (personal Microsoft account) AplicaciónApplication
contactocontact Contacts.ReadContacts.Read Contacts.ReadContacts.Read Contacts.ReadContacts.Read
driveItem (OneDrive personal del usuario)driveItem (user's personal OneDrive) No admitidoNot supported Files.ReadWriteFiles.ReadWrite No admitidoNot supported
driveItem (OneDrive para la Empresa)driveItem (OneDrive for Business) Files.ReadWrite.AllFiles.ReadWrite.All No admitidoNot supported Files.ReadWrite.AllFiles.ReadWrite.All
eventoevent Calendars.ReadCalendars.Read Calendars.ReadCalendars.Read Calendars.ReadCalendars.Read
grupogroup Group.Read.AllGroup.Read.All No admitidoNot supported Group.Read.AllGroup.Read.All
conversación de grupogroup conversation Group.Read.AllGroup.Read.All No admitidoNot supported No admitidoNot supported
mensajemessage Mail.ReadMail.Read Mail.ReadMail.Read Mail.ReadMail.Read
alerta de seguridadsecurity alert SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All No admitidoNot supported SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All
usuariouser User.Read.AllUser.Read.All User.Read.AllUser.Read.All User.Read.AllUser.Read.All

Nota: Hay limitaciones adicionales para las suscripciones en los elementos de Outlook y OneDrive.Note: There are additional limitations for subscriptions on OneDrive and Outlook items. Se aplican dichas limitaciones para crear y administrar suscripciones (para obtener, actualizar y eliminar suscripciones).The limitations apply to creating as well as managing subscriptions (getting, updating, and deleting subscriptions).

  • En OneDrive personal, puede suscribirse a la carpeta raíz o cualquier subcarpeta de la unidad.On personal OneDrive, you can subscribe to the root folder or any subfolder in that drive. En OneDrive para la Empresa, puede suscribirse solo a la carpeta raíz.On OneDrive for Business, you can subscribe to only the root folder. Se envían las notificaciones para los tipos de cambios solicitados en la carpeta suscrita o cualquier archivo, carpeta o en otras instancias de driveItem de su jerarquía.Notifications are sent for the requested types of changes on the subscribed folder, or any file, folder, or other driveItem instances in its hierarchy. No puede suscribirse a instancias de drive o driveItem que no sean carpetas, como archivos individuales.You cannot subscribe to drive or driveItem instances that are not folders, such as individual files.

  • En Outlook, un permiso delegado es compatible con la suscripción a los elementos de carpetas que se encuentran solo en el buzón del usuario que ha iniciado sesión.In Outlook, delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. Eso significa que, por ejemplo, no puede usar el permiso delegado Calendars.Read para suscribirse a eventos en el buzón de otro usuario.That means, for example, you cannot use the delegated permission Calendars.Read to subscribe to events in another user’s mailbox.

  • Para suscribirse y cambiar las notificaciones de eventos, contactos o mensajes de Outlook en carpetas compartidas o delegadas:To subscribe to change notifications of Outlook contacts, events, or messages in shared or delegated folders:

    • Use los permisos de aplicación correspondientes para suscribirse a los cambios de los elementos de una carpeta o un buzón de cualquier usuario del espacio empresarial.Use the corresponding application permission to subscribe to changes of items in a folder or mailbox of any user in the tenant.
    • No use los permisos de uso compartido de Outlook (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared y sus equivalentes de lectura y escritura), ya que no admiten la suscripción para cambiar las notificaciones en elementos de carpetas delegadas o compartidas.Do not use the Outlook sharing permissions (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared, and their read/write counterparts), as they do not support subscribing to change notifications on items in shared or delegated folders.

Solicitud HTTPHTTP request

POST /subscriptions

Encabezados de solicitudRequest headers

NombreName TipoType DescripciónDescription
AuthorizationAuthorization stringstring {token} de portador. Obligatorio.Bearer {token}. Required.

RespuestaResponse

Si se ejecuta correctamente, este método devuelve un código de respuesta 201 Created y un objeto de suscripción en el cuerpo de la respuesta.If successful, this method returns 201 Created response code and a subscription object in the response body.

EjemploExample

SolicitudRequest

Este es un ejemplo de solicitud para enviar una notificación cuando el usuario recibe un nuevo correo electrónico.Here is an example of the request to send a notification when the user receives a new mail.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
   "changeType": "created,updated",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "me/mailFolders('Inbox')/messages",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue"
}

En el cuerpo de la solicitud, proporcione una representación JSON del objeto subscription.In the request body, supply a JSON representation of the subscription object. El campo clientState es opcional.The clientState field is optional.

Ejemplos de recursosResources examples

A continuación puede ver algunos valores válidos para la propiedad de recurso de la suscripción:The following are valid values for the resource property of the subscription:

Tipo de recursoResource type EjemplosExamples
CorreoMail me/mailfolders("inbox")/messagesme/mailfolders('inbox')/messages
me/messagesme/messages
ContactosContacts me/contactsme/contacts
CalendariosCalendars me/eventsme/events
UsuariosUsers usersusers
GruposGroups groupsgroups
ConversacionesConversations groups("{id}")/conversationsgroups('{id}')/conversations
UnidadesDrives me/drive/rootme/drive/root
Alerta de seguridadSecurity alert security/alerts?$filter=status eq ‘New’security/alerts?$filter=status eq ‘New’
RespuestaResponse

Aquí tiene un ejemplo de la respuesta. Nota: Puede que el objeto de respuesta que aparece aquí se trunque para abreviar. Todas las propiedades se devolverán de una llamada real.Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 201 Created
Content-type: application/json
Content-length: 252

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#subscriptions/$entity",
  "id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource": "me/mailFolders('Inbox')/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType": "created,updated",
  "clientState": "secretClientValue",
  "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "expirationDateTime": "2016-11-20T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437"
}

Validación de extremo de notificaciónNotification endpoint validation

El extremo de notificación de la suscripción (especificado en la propiedad notificationUrl) debe poder responder a una solicitud de validación, como se describe en Configurar las notificaciones para cambios en los datos de usuario.The subscription notification endpoint (specified in the notificationUrl property) must be capable of responding to a validation request as described in Set up notifications for changes in user data. Si se produce un error de validación, la solicitud para crear la suscripción devuelve un error 400 de solicitud incorrecta.If validation fails, the request to create the subscription returns a 400 Bad Request error.