Crear suscripciónCreate subscription

Espacio de nombres: microsoft.graphNamespace: microsoft.graph

Suscribe una aplicación de escucha para que reciba notificaciones de cambio cuando se realiza el tipo de cambios solicitado en el recurso especificado de Microsoft Graph.Subscribes a listener application to receive change 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 cambio de mensajes, la aplicación necesita el permiso Mail.Read.For example, to get change 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
callRecord (/communications/callRecords)callRecord (/communications/callRecords) No compatibleNot supported No compatibleNot supported CallRecords.Read.AllCallRecords.Read.All
chatMessage (/equipos/{id}/canales/{id}/mensajes)chatMessage (/teams/{id}/channels/{id}/messages) No admitidoNot supported No admitidoNot supported ChannelMessage.Read.AllChannelMessage.Read.All
chatMessage (/equipos/getAllMessages -- todos los mensajes del canal en la organización)chatMessage (/teams/getAllMessages -- all channel messages in organization) No admitidoNot supported No admitidoNot supported ChannelMessage.Read.AllChannelMessage.Read.All
chatMessage (/chats/{id}/mensajes)chatMessage (/chats/{id}/messages) No admitidoNot supported No admitidoNot supported Chat.Read.AllChat.Read.All
chatMessage (/chats/getAllMessages -- todos los mensajes de chat en la organización)chatMessage (/chats/getAllMessages -- all chat messages in organization) No admitidoNot supported No admitidoNot supported Chat.Read.AllChat.Read.All
contactcontact 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 se admiteNot supported
listalist Sites.ReadWrite.AllSites.ReadWrite.All No se admiteNot supported Sites.ReadWrite.AllSites.ReadWrite.All
messagemessage Mail.ReadBasic, Mail.ReadMail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.ReadMail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.ReadMail.ReadBasic, Mail.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

chatMessagechatMessage

Las suscripciones de chatMessage con permisos de aplicación incluyen datos de recursos, y requieren cifrado.chatMessage subscriptions with application permissions include resource data, and require encryption. La creación de la suscripción fallará si no se especifica encryptionCertificate.Subscription creation will fail if encryptionCertificate is not specified. Antes de crear una suscripción de chatMessage, debe solicitar el acceso.Before creating a chatMessage subscription, you must request access. Para obtener más información, vea API protegidas en Microsoft Teams.For details, see Protected APIs in Microsoft Teams.

Nota: /teams/getAllMessages y /chats/getAllMessages están disponibles para los usuarios que tengan las licencias necesarias.Note: /teams/getAllMessages and /chats/getAllMessages are available to users that have the required licenses.

driveItemdriveItem

Se aplicarán otras limitaciones a las suscripciones de los elementos de OneDrive.Additional limitations apply for subscriptions on OneDrive 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 (getting, updating, and deleting) subscriptions.

En un OneDrive personal, puede suscribirse a la carpeta raíz o cualquier subcarpeta de la unidad.On a 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 de cambio para los tipos de cambios solicitados en la carpeta suscrita o cualquier archivo, carpeta o en otras instancias de driveItem de su jerarquía.Change 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.

contacto, evento y mensajecontact, event, and message

Se aplicarán otras limitaciones a las suscripciones de los elementos de Outlook.Additional limitations apply for subscriptions on 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 (getting, updating, and deleting) subscriptions.

  • El permiso delegado permite suscribirse a los elementos de las carpetas que sólo se encuentran en el buzón del usuario que ha iniciado la sesión.Delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. Por ejemplo, no puede utilizar el permiso delegado Calendars.Read para suscribirse a eventos en el buzón de otro usuario.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. Vea Respuestas de error para obtener detalles sobre la manera en que se devuelven los errores.For details about how errors are returned, see Error responses.

EjemploExample

SolicitudRequest

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

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

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

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. Los campos clientState y latestSupportedTlsVersion son opcionales.The clientState and latestSupportedTlsVersion fields are 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
Registros de llamadasCall records communications/callRecords
Mensaje de chatChat message chats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessageschats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessages
ContactosContacts me/contacts
ConversacionesConversations groups('{id}')/conversations
UnidadesDrives me/drive/root
EventosEvents me/events
GruposGroups groups
ListaList sites/{site-id}/lists/{list-id}
CorreoMail me/mailfolders('inbox')/messages, me/messagesme/mailfolders('inbox')/messages, me/messages
UsuariosUsers users
Alerta de seguridadSecurity alert security/alerts?$filter=status eq 'New'

Nota: cualquier ruta de acceso que comience con me también se puede usar con users/{id} en lugar de me para establecer como destino un usuario específico en lugar del usuario actual.Note: Any path starting with me can also be used with users/{id} instead of me to target a specific user instead of the current user.

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/v1.0/$metadata#subscriptions/$entity",
  "id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource": "me/mailFolders('Inbox')/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType": "created",
  "clientState": "secretClientValue",
  "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "expirationDateTime": "2016-11-20T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
  "latestSupportedTlsVersion": "v1_2"
}

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.