Referencia de la API de REST de extensiones de datos de Office 365

Se aplica a: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Nota

Esta documentación cubre la versión beta de la API de extensiones de datos de Office 365 en estado de vista previa. Las características en versión preliminar pueden cambiar antes de su finalización, y pueden dañar código que las utilice. Por ello, en general, debería utilizar solo una versión de producción de una API en su código de producción. Si está disponible, la v2.0 es actualmente la versión preferida.

La API REST de extensiones de datos de Office 365 permite a las aplicaciones almacenar datos personalizados de forma dinámica en un mensaje, evento o contacto de la cuenta del usuario. La cuenta puede estar en Office 365 o ser una cuenta Microsoft (Hotmail.com, Live.com, MSN.com, Outlook.com y Passport.com).

Nota

Para facilitar la referencia, en el resto de este artículo se utiliza Outlook.com para englobar a estos dominios de cuentas Microsoft.

¿No está interesado en la versión beta de la API? En el índice de la izquierda, vaya a la sección Referencia de la API REST de Office 365 y seleccione la versión que desee.

Información general

Una extensión de datos en la API REST de Outlook es un tipo abierto de OData v4 que contiene propiedades que puede especificar en el tiempo de ejecución. Puede usar la API de extensiones de datos para ampliar una instancia de un tipo de entidad ya definido en el Entity Data Model (EDM) (un mensaje, evento o contacto) especificando propiedades y valores personalizados de forma dinámica en una carga útil de JSON. Esto hace que la definición de dichos tipos de entidad sea más flexible, lo que le ahorra tiempo para definir nuevos tipos de entidades solo para este propósito.

La propiedad ExtensionName es la única que está definida en todas las extensiones. Una forma de asegurarse de que los nombres de extensión son únicos es usar un sistema inverso del formato de nombres de dominio (DNS) que dependa de su propio dominio, por ejemplo, Com.Contoso.Contact. No use el dominio de Microsoft en un nombre de extensión.

Como las extensiones son de tipo abierto, puede introducir datos adicionales específicos en una instancia de una entidad. Por ejemplo, puede crear una extensión para contactos comerciales individuales que haga un seguimiento de los datos personalizados, como el nombre de la empresa y la referencia inicial, y especificar los datos en la carga útil de JSON de la siguiente manera:

POST https://outlook.office.com/api/beta/me/contacts('{contact_id}')/extensions
{
   @odata.type: "Microsoft.OutlookServices.OpenTypeExtension",  
   "ExtensionName": "Com.Contoso.Customer",
   "CompanyName": "Alpine Skis",
   "InitialReferrer":  "Robin McCall"
}

Puede usar la API de extensiones de datos para realizar operaciones CRUD en un recurso nuevo o uno que ya exista. Obtenga más información sobre las operaciones admitidas.

Para obtener más información sobre el tipo abierto de OData, consulte la documentación de OData v4 en OData.org.

Uso de la API REST de extensiones de datos

¿Extensiones de datos o propiedades extendidas?

Las extensiones de datos son la solución recomendada para la mayoría de los escenarios que implican el almacenamiento y el acceso a datos personalizados. Sin embargo, si necesita acceder a datos personalizados para las propiedades MAPI de Outlook que aún no están expuestas a través de los metadatos de la API REST de Outlook, puede usar las propiedades extendidas y su API REST. Puede verificar qué propiedades exponen los metadatos en https://outlook.office.com/api/{version}/$metadata, sustituyendo {version} por v2.0, beta, etc., según la versión que corresponda en su caso.

Autenticación

Como cualquier otra API REST de Outlook, para cada solicitud a la API de extensiones de datos, debería incluir un token de acceso válido. Obtener un token de acceso requiere que haya registrado e identificado su aplicación y obtenido la autorización correspondiente.

Puede obtener más información sobre algunas opciones de registro y autorización optimizadas para usted. Tenga esto en cuenta a medida que avance con las operaciones específicas en la API de extensiones de datos.

Recursos de REST admitidos

Puede crear extensiones para instancias de los siguientes recursos en el punto de conexión REST de Outlook:

• Mensaje
• Evento
• Contacto

Versión de la API

El estado de esta API ha ascendido de versión preliminar a disponibilidad general. Es compatible con las versiones 2.0 y beta:

https://outlook.office.com/api/v2.0/

https://outlook.office.com/api/beta/

Parámetros de dirección URL

Los ejemplos de este artículo utilizan los siguientes marcadores de posición de id. en parámetros de las URL de solicitud de REST. Debe especificar el id. de la instancia de recurso para la que desee crear una extensión.

Parámetro	Tipo	Descripción
Parámetros de la dirección URL
contact_id	cadena	El identificador.
event_id	cadena	Id. de evento.
message_id	cadena	El id.

Consulte el artículo Use the Outlook REST API (Usar la API REST de Outlook) para obtener más información relacionada con los subconjuntos de la API REST de Outlook y la API REST de extensiones de datos de Office 365.

Operaciones de extensión

• Crear extensión en un elemento existente
• Crear extensión en un nuevo elemento
• Obtener una extensión
• Expandir elemento con una extensión
• Buscar y expandir elementos con una extensión
• Añadir o modificar datos en una extensión
• Eliminar una extensión

Crear extensión en un elemento existente

Cree una extensión y añada propiedades personalizadas en la instancia especificada de un recurso. El recurso puede ser un mensaje, un evento de calendario o un contacto de Office 365 o Outlook.com. Los datos en la carga útil de JSON pueden ser tipos primitivos o matrices de tipos primitivos.

Para crear una extensión a cada uno de los recursos admitidos:

POST https://outlook.office.com/api/beta/me/messages('{message_id}')/extensions
POST https://outlook.office.com/api/beta/me/events('{event_id}')/extensions
POST https://outlook.office.com/api/beta/me/contacts('{contact_id}')/extensions

Ámbito mínimo necesario

Uno de los siguientes ámbitos de lectura y escritura correspondiente al recurso de destino:

• https://outlook.office.com/mail.readwrite
• https://outlook.office.com/calendars.readwrite
• https://outlook.office.com/contacts.readwrite
• wl.imap
• wl.calendars_update
• wl.events_create
• wl.contacts_create

Parámetro	Tipo	Descripción
Parámetros de cuerpo
ExtensionName	cadena	Identificador de texto único para una extensión. Necesario.

Solicitud de muestra

Este ejemplo crea una extensión para el mensaje especificado. El cuerpo de la solicitud incluye los siguiente elementos en la extensión:

• El tipo Microsoft.OutlookServices.OpenTypeExtension que se define como un tipo abierto de OData en los metadatos de la api de rest de Outlook.
• El nombre de la extensión "Com.Contoso.Referral".
• Datos adicionales que deben ser almacenados como propiedades personalizadas en la carga útil de JSON:CompanyName,DealValue yExpirationDate que contienen tipos primitivos, y TopModels yTopSalespersons que contienen matrices de tipos primitivos.

POST https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions

Content-Type: application/json

{ 
  "@odata.type" : "Microsoft.OutlookServices.OpenTypeExtension", 
  "ExtensionName" : "Com.Contoso.Referral", 
  "CompanyName" : "Wingtip Toys",
  "DealValue@odata.type": "#Int64", 
  "DealValue" : 500050, 
  "ExpirationDate" : "2015-12-03T10:00:00.000Z",
  "TopModels": [
     3001,
     4002,
     5003
  ],
  "TopSalespersons": [
     "Dana Swope",
     "Fanny Downs",
     "Randi Welch"
  ]
} 

Respuesta de muestra

Una respuesta correcta se indica mediante un código de respuesta HTTP 201 Created.

El cuerpo de la respuesta incluye los siguiente elementos en la nueva extensión:

• La propiedad predeterminada extensionName.
• La propiedad id con el nombre completo Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral.
• Los datos personalizados que se almacenarán.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "ExtensionName": "Com.Contoso.Referral",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys",
    "DealValue@odata.type": "#Int64",
    "DealValue": 500050,
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "TopModels@odata.type": "#Collection(Int32)",
    "TopModels": [
      3001,
      4002,
      5003
    ],
    "TopSalespersons@odata.type": "#Collection(String)",
    "TopSalespersons": [
      "Dana Swope",
      "Fanny Downs",
      "Randi Welch"
    ]
}

Crear extensión en un nuevo elemento

Cree una o más extensiones mientras crea una nueva instancia de un recurso, todas en la misma llamada POST, y añada propiedades personalizadas a la extensión. El recurso puede ser un mensaje, un evento de calendario o un contacto de Office 365 o Outlook.com. Los datos en la carga útil de JSON pueden ser tipos primitivos o matrices de tipos primitivos.

Para crear una extensión de cada uno de los recursos admitidos, realice una llamada POST similar a la creación de ese recurso e incluya una extensión en el cuerpo de la solicitud POST.

POST https://outlook.office.com/api/beta/me/messages
POST https://outlook.office.com/api/beta/me/events
POST https://outlook.office.com/api/beta/me/contacts

Ámbito mínimo necesario

Uno de los siguientes ámbitos de lectura y escritura correspondiente al recurso de destino:

• https://outlook.office.com/mail.readwrite
• https://outlook.office.com/calendars.readwrite
• https://outlook.office.com/contacts.readwrite
• wl.imap
• wl.calendars_update
• wl.events_create
• wl.contacts_create

Parámetro	Tipo	Descripción
Parámetros de cuerpo
ExtensionName	cadena	Identificador de texto único para una extensión. Necesario.

Solicitud de muestra

En este ejemplo se crea un mensaje y una extensión en la misma llamada. El cuerpo de la solicitud incluye los siguientes elementos:

• Las propiedades subject, body y toRecipients típicas de un nuevo mensaje.
• Y en cuanto a la extensión:
  • El tipo Microsoft.OutlookServices.OpenTypeExtension que se define como un tipo abierto de OData en los metadatos de la API de REST de Outlook.
  • El nombre de la extensión "Com.Contoso.Referral".
  • Datos adicionales que deben ser almacenados como propiedades personalizadas en la carga útil de JSON:CompanyName,ExpirationDate yDealValue que contienen tipos primitivos, y TopModels yTopSalespersons que contienen matrices de tipos primitivos.

POST https://outlook.office.com/api/beta/me/messages

Content-Type: application/json

{
  "Subject": "Annual review",
  "Body": {
    "ContentType": "HTML",
    "Content": "You should be proud!"
  },
  "ToRecipients": [
    {
      "EmailAddress": {
        "Address": "rufus@contoso.com"
      }
    }
  ],
  "Extensions": [
    {
      "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
      "ExtensionName": "Com.Contoso.Referral",
      "CompanyName": "Wingtip Toys",
      "ExpirationDate": "2015-12-30T11:00:00.000Z",
      "DealValue": 10000,
      "TopModels": [
        3001,
        4002,
        5003
      ],
      "TopSalespersons": [
        "Dana Swope",
        "Fanny Downs",
        "Randi Welch"
      ]
    }
  ]
}

Respuesta de muestra

Una respuesta correcta se indica mediante un código de respuesta HTTP 201 Created.

El cuerpo de la respuesta incluye las propiedades del mensaje nuevo y lo siguiente para la nueva extensión:

• La propiedad id con el nombre completo Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral.
• La propiedad predeterminada extensionName especificada en la solicitud.
• Los datos personalizados especificados en la solicitud y almacenados como propiedades personalizadas.

{
  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
  "@odata.id": "https://outlook.office.com/api/beta/Users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/Messages
('AAMkAGEbs88AAB84uLuAAA=')",
  "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj\"",
  "Id": "AAMkAGEbs88AAB84uLuAAA=",
  "CreatedDateTime": "2015-10-30T03:03:43Z",
  "LastModifiedDateTime": "2015-10-30T03:03:43Z",
  "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj",
  "Categories": [ ],
  "ReceivedDateTime": "2015-10-30T03:03:43Z",
  "SentDateTime": "2015-10-30T03:03:43Z",
  "HasAttachments": false,
  "Subject": "Annual review",
  "Body": {
    "ContentType": "HTML",
    "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r
\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nYou should be proud!\r\n</body>\r
\n</html>\r\n"
  },
  "BodyPreview": "You should be proud!",
  "Importance": "Normal",
  "ParentFolderId": "AQMkAGEwAAAIBDwAAAA==",
  "Sender": null,
  "From": null,
  "ToRecipients": [
    {
      "EmailAddress": {
        "Address": "rufus@contoso.com",
        "Name": "John Doe"
      }
    }
  ],
  "CcRecipients": [ ],
  "BccRecipients": [ ],
  "ReplyTo": [ ],
  "ConversationId": "AAQkAGEFGugh3SVdMzzc=",
  "IsDeliveryReceiptRequested": false,
  "IsReadReceiptRequested": false,
  "IsRead": true,
  "IsDraft": true,
  "WebLink": "https://outlook.office.com/owa/?
ItemID=AAMkAGEbs88AAB84uLuAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
  "MentionedMe": null,
  "Mentioned": [ ],
  "InferenceClassification": "Focused",
  "Extensions@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages
('AAMkAGEbs88AAB84uLuAAA%3D')/Extensions",
  "Extensions": [
    {
      "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
      "@odata.id": "https://outlook.office.com/api/beta/Users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/Messages
('AAMkAGEbs88AAB84uLuAAA=')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
      "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
      "ExtensionName": "Com.Contoso.Referral",
      "CompanyName": "Wingtip Toys",
      "ExpirationDate": "2015-12-30T11:00:00.000Z",
      "DealValue": 10000,
      "TopModels@odata.type": "#Collection(Int32)",
      "TopModels": [
        3001,
        4002,
        5003
      ],
      "TopSalespersons@odata.type": "#Collection(String)",
      "TopSalespersons": [
        "Dana Swope",
        "Fanny Downs",
        "Randi Welch"
      ]
    }
  ]
}

Obtener extensión

Obtenga una extensión por nombre o ID dentro de la instancia especificada de un recurso. El recurso puede ser un mensaje, un evento de calendario o un contacto de Office 365 o Outlook.com.

Si obtiene la extensión por nombre o por ID, se le devuelve el mismo cuerpo de respuesta.

GET https://outlook.office.com/api/beta/me/messages('{message_id}')/extensions('{extensionId}')
GET https://outlook.office.com/api/beta/me/events('{event_id}')/extensions('{extensionId}')
GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')/extensions('{extensionId}')

Ámbito mínimo necesario

Uno de los siguientes ámbitos de lectura correspondiente al recurso de destino:

• https://outlook.office.com/mail.read
• https://outlook.office.com/calendars.read
• https://outlook.office.com/contacts.read
• wl.imap
• wl.calendars
• wl.contacts_calendars
• wl.basic

Parámetro	Tipo	Descripción
Parámetro URL
extensionId	cadena	Esto puede ser un nombre de extensión que sea un identificador de texto único entre todas las extensiones de una instancia de recurso, o un nombre completo que concatena el tipo de extensión y el identificador de texto único. El nombre completo se devuelve en la propiedad id cuando crea la extensión. Necesario.

Solicitud de muestra

En el primer ejemplo, se hace referencia a una extensión por su nombre y se obtiene la extensión en el mensaje especificado.

GET https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Com.Contoso.Referral')

En el segundo ejemplo, se hace referencia a una extensión por su ID (nombre completo) y se obtiene la extensión en el mensaje especificado.

GET https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Respuesta de muestra

Una respuesta correcta se indica mediante un código de respuesta HTTP 200 OK.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "ExtensionName": "Com.Contoso.Referral",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys",
    "DealValue": 500050,
    "ExpirationDate": "2015-12-03T10:00:00Z"
}

Expandir elemento con extensión

Expanda una instancia de un recurso con la extensión especificada por un filtro en Id. El recurso puede ser un mensaje, un evento de calendario o un contacto de Office 365 o Outlook.com.

Puede filtrar en Id contra el nombre de la extensión o el nombre completo, y luego expandir la instancia con la extensión como se muestra a continuación. Asegúrese de aplicar la codificación de URL a los caracteres de espacio de la cadena de filtro.

GET https://outlook.office.com/api/beta/me/messages('{message_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/beta/me/events('{event_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

Ámbito mínimo necesario

Uno de los siguientes ámbitos de lectura correspondiente al recurso de destino:

• https://outlook.office.com/mail.read
• https://outlook.office.com/calendars.read
• https://outlook.office.com/contacts.read
• wl.imap
• wl.calendars
• wl.contacts_calendars
• wl.basic

Parámetro	Tipo	Descripción
Parámetro URL
extensionId	cadena	Esto puede ser un nombre de extensión que sea un identificador de texto único entre todas las extensiones de una instancia de recurso, o un nombre completo que concatena el tipo de extensión y el identificador de texto único. El nombre completo se devuelve en la propiedad id cuando crea la extensión. Necesario.

Solicitud de muestra

En el siguiente ejemplo, se obtiene y se expande el mensaje especificado incluyendo la extensión devuelta desde un filtro. El filtro devuelve la extensión cuyo Id coincide con un nombre completo.

Para su comodidad, la solicitud se muestra a continuación con la codificación URL del carácter o espacio reservado.

GET https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')?$expand=Extensions($filter=Id%20eq%20'Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Respuesta de muestra

Una respuesta correcta se indica mediante un código de respuesta HTTP 200 OK.

El cuerpo de la respuesta incluye todas las propiedades del mensaje especificado y la extensión que devuelve el filtro.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM\"",
    "Id": "AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM",
    "Categories": [
    ],
    "CreateDateTime": "2015-06-19T02:03:31Z",
    "LastModifiedDateTime": "2015-08-13T02:28:00Z",
    "Subject": "Attached is the requested info",
    "BodyPreview": "See the images attached.",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"><!-- P {margin-top:0;margin-bottom:0;} --></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt;color:#000000;background-color:#FFFFFF;font-family:Calibri,Arial,Helvetica,sans-serif;\">\r\n<p>See the images attached. <br>\r\n</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "Importance": "Normal",
    "HasAttachments": true,
    "ParentFolderId": "AQMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===QAAAA==",
    "From": {
        "EmailAddress": {
            "Address": "desmond@contoso.com",
            "Name": "Desmond Raley"
        }
    },
    "Sender": {
        "EmailAddress": {
            "Address": "desmond@contoso.com",
            "Name": "Desmond Raley"
        }
    },
    "ToRecipients": [
        {
            "EmailAddress": {
                "Address": "wendy@contoso.com",
                "Name": "Wendy Molina"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===mivdTmQ=",
    "ReceivedDateTime": "2015-06-19T02:05:04Z",
    "SentDateTime": "2015-06-19T02:04:59Z",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsDraft": false,
    "IsRead": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===%2FNJTqt5NqHlVnKVBwCY4MQpaFz9SbqUDe4%2Bbs88AAAAAAEJAACY4MQpaFz9SbqUDe4%2Bbs88AAApA4JMAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "Extensions@odata.context": "https://outlook.office.com/api/beta/$metadata#Users('desmond40contoso.com')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions", 
    "Extensions": [ 
      { 
        "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
        "@odata.id": "https://outlook.office.com/api/beta/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
        "ExtensionName": "Com.Contoso.Referral",
        "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
        "CompanyName": "Wingtip Toys",
        "DealValue": 500050,
        "ExpirationDate": "2015-12-03T10:00:00Z"
      }
     ]
}

Buscar y expandir artículos con una extensión

Puede encontrar instancias de un recurso que contengan una extensión que coincida con un filtro. Además, en la misma consulta, puede expandir estas instancias con la extensión. Las consultas en esta sección encuentran estas instancias, expanden e incluyen la extensión en la respuesta.

El recurso puede ser un mensaje, un evento de calendario o un contacto de Office 365 o Outlook.com.

Puede filtrar en Id contra el nombre de la extensión o el nombre completo, y luego expandir la instancia con la extensión como se muestra a continuación. Asegúrese de aplicar la codificación de URL a los caracteres de espacio de la cadena de filtro.

GET https://outlook.office.com/api/beta/me/messages?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/beta/me/events?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/beta/me/contacts?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

Ámbito mínimo necesario

Uno de los siguientes ámbitos de lectura correspondiente al recurso de destino:

• https://outlook.office.com/mail.read
• https://outlook.office.com/calendars.read
• https://outlook.office.com/contacts.read
• wl.imap
• wl.calendars
• wl.contacts_calendars
• wl.basic

Parámetro	Tipo	Descripción
Parámetro URL
extensionId	cadena	Esto puede ser un nombre de extensión que sea un identificador de texto único entre todas las extensiones de una instancia de recurso, o un nombre completo que concatena el tipo de extensión y el identificador de texto único. El nombre completo se devuelve en la propiedad id cuando crea la extensión. Necesario.

Solicitud de muestra

El siguiente ejemplo busca todos los mensajes en el buzón del usuario que ha iniciado sesión para encontrar aquellos que contienen una extensión que coincide con un filtro, y los expande incluyendo la extensión. El filtro devuelve extensiones cuyo Id coincide con el nombre de la extensión Com.Contoso.Referral.

Para su comodidad, la solicitud se muestra a continuación con la codificación URL del carácter o espacio reservado.

GET https://outlook.office.com/api/beta/me/messages?$filter=Extensions/any(f:f/Id%20eq%20'Com.Contoso.Referral')&$expand=Extensions($filter=Id%20eq%20'Com.Contoso.Referral')

Respuesta de muestra

Una respuesta correcta se indica mediante un código de respuesta HTTP 200 OK.

El cuerpo de la respuesta incluye todos los mensajes que tienen una extensión coincidente y todas las propiedades del mensaje. En este ejemplo, la respuesta contiene dos mensajes.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages",
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.EventMessage",
            "@odata.id": "https://outlook.office.com/api/beta/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyDREAAA=')",
            "@odata.etag": "W/\"DAAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ9tn\"",
            "Id": "AAMkADIyDREAAA=",
            "CreatedDateTime": "2016-01-06T02:20:17Z",
            "LastModifiedDateTime": "2016-01-13T02:13:54Z",
            "ChangeKey": "DAAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ9tn",
            "Categories": [
            ],
            "ReceivedDateTime": "2016-01-06T02:20:18Z",
            "SentDateTime": "2016-01-06T02:20:18Z",
            "HasAttachments": false,
            "InternetMessageId": "<BY1PR19MB0023E92E0B43F5E268406F0DF5F40@BY1PR19MB0023.namprd19.prod.outlook.com>",
            "Subject": "Accepted: Latin American Product Manual Group",
            "Body": {
                "ContentType": "Text",
                "Content": ""
            },
            "BodyPreview": "",
            "Importance": "Normal",
            "ParentFolderId": "AAMkADIyAAAAEJAAA=",
            "Sender": {
                "EmailAddress": {
                    "Name": "MOD Administrator",
                    "Address": "admin@adatumltd.onmicrosoft.com"
                }
            },
            "From": {
                "EmailAddress": {
                    "Name": "MOD Administrator",
                    "Address": "admin@adatumltd.onmicrosoft.com"
                }
            },
            "ToRecipients": [
                {
                    "EmailAddress": {
                        "Name": "Engineering",
                        "Address": "engineering@adatumltd.onmicrosoft.com"
                    }
                }
            ],
            "CcRecipients": [
            ],
            "BccRecipients": [
            ],
            "ReplyTo": [
            ],
            "ConversationId": "AAQkADIyWejUoYAg=",
            "IsDeliveryReceiptRequested": null,
            "IsReadReceiptRequested": false,
            "IsRead": true,
            "IsDraft": false,
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADIyDREAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "InferenceClassification": "Focused",
            "UnsubscribeData": [
            ],
            "UnsubscribeEnabled": false,
            "MeetingMessageType": "MeetingAccepted",
            "StartDateTime": {
                "DateTime": "2015-01-05T19:00:00.0000000",
                "TimeZone": "UTC"
            },
            "EndDateTime": {
                "DateTime": "2015-01-05T20:30:00.0000000",
                "TimeZone": "UTC"
            },
            "Location": {
                "DisplayName": "Mt. Adams"
            },
            "Type": "SeriesMaster",
            "Recurrence": {
                "Pattern": {
                    "Type": "RelativeMonthly",
                    "Interval": 2,
                    "Month": 0,
                    "DayOfMonth": 0,
                    "DaysOfWeek": [
                        "Monday"
                    ],
                    "FirstDayOfWeek": "Sunday",
                    "Index": "First"
                },
                "Range": {
                    "Type": "NoEnd",
                    "StartDate": "2015-01-05",
                    "EndDate": "0001-01-01",
                    "RecurrenceTimeZone": "tzone://Microsoft/Utc",
                    "NumberOfOccurrences": 0
                }
            },
            "IsOutOfDate": false,
            "Extensions@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkADIyDREAAA%3D')/Extensions",
            "Extensions": [
                {
                    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
                    "@odata.id": "https://outlook.office.com/api/beta/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyDREAAA=')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
                    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
                    "ExtensionName": "Com.Contoso.Referral",
                    "CompanyName": "Wingtip Toys",
                    "DealValue@odata.type": "#Int64",
                    "DealValue": 500300,
                    "ExpirationDate": "2015-12-03T10:00:00.000Z"
                }
            ],
            "Event@odata.associationLink": "https://outlook.office.com/api/beta/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Events('AAMkADIyAAAAABrdAAA=')/$ref",
            "Event@odata.navigationLink": "https://outlook.office.com/api/beta/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Events('AAMkADIyAAAAABrdAAA=')"
        },
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyAHVAAA=')",
            "@odata.etag": "W/\"CQAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ6aq\"",
            "Id": "AAMkADIyAHVAAA=",
            "CreatedDateTime": "2016-01-06T02:20:02Z",
            "LastModifiedDateTime": "2016-01-13T02:24:50Z",
            "ChangeKey": "CQAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ6aq",
            "Categories": [
            ],
            "ReceivedDateTime": "2016-01-06T02:20:02Z",
            "SentDateTime": "2016-01-06T02:20:01Z",
            "HasAttachments": false,
            "InternetMessageId": "<CY1PR19MB0032531C620A46068FDDD45DE3F40@CY1PR19MB0032.namprd19.prod.outlook.com>",
            "Subject": "International Launch Planning for XT2000",
            "Body": {
                "ContentType": "HTML",
                "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nWe will be ready to ship XT 2000 on 10/1, how's the International launch plan going?<br>\r\n<div style=\"display:inline-block\">\r\n<table border=\"0\" cellspacing=\"0\" style=\"background-color:#F4F4F4\">\r\n<tbody>\r\n<tr>\r\n<td style=\"padding:20px; font-size:12px; color:#666666\">You're receiving this message because you're a subscribed member of the Engineering group.<br>\r\n<a href=\"https://outlook.office.com/owa/engineering@adatumltd.onmicrosoft.com/groupsubscription.ashx?realm=adatumltd.onmicrosoft.com&amp;action=conversations&amp;source=EscalatedMessage\">View group conversations</a> |\r\n<a href=\"https://adatumltd.sharepoint.com/_layouts/groupstatus.aspx?id=dbcbe107-6244-40ba-b0f1-1c46ad35435d&amp;target=documents\">\r\nView group files</a> | <a id=\"BD5134C6-8D33-4ABA-A0C4-08581FDF89DB\" href=\"https://outlook.office.com/owa/engineering@adatumltd.onmicrosoft.com/groupsubscription.ashx?realm=adatumltd.onmicrosoft.com&amp;action=unsubscribe&amp;source=EscalatedMessage\">\r\nUnsubscribe</a></td>\r\n</tr>\r\n</tbody>\r\n</table>\r\n</div>\r\n</body>\r\n</html>\r\n"
            },
            "BodyPreview": "We will be ready to ship XT 2000 on 10/1, how's the International launch plan going?\r\nYou're receiving this message because you're a subscribed member of the Engineering group.\r\nView group conversations | View group files | Unsubscribe",
            "Importance": "Normal",
            "ParentFolderId": "AAMkADIyAAAEMAAA=",
            "Sender": {
                "EmailAddress": {
                    "Name": "Engineering",
                    "Address": "engineering@adatumltd.onmicrosoft.com"
                }
            },
            "From": {
                "EmailAddress": {
                    "Name": "Garret Vargas",
                    "Address": "GarretV@adatumltd.onmicrosoft.com"
                }
            },
            "ToRecipients": [
                {
                    "EmailAddress": {
                        "Name": "Engineering",
                        "Address": "engineering@adatumltd.onmicrosoft.com"
                    }
                }
            ],
            "CcRecipients": [
            ],
            "BccRecipients": [
            ],
            "ReplyTo": [
            ],
            "ConversationId": "AAQkADIyLESZnSPc=",
            "IsDeliveryReceiptRequested": null,
            "IsReadReceiptRequested": false,
            "IsRead": false,
            "IsDraft": false,
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADIyAHVAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "InferenceClassification": "Focused",
            "UnsubscribeData": [
            ],
            "UnsubscribeEnabled": false,
            "Extensions@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkADIyAHVAAA%3D')/Extensions",
            "Extensions": [
                {
                    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
                    "@odata.id": "https://outlook.office.com/api/beta/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyAHVAAA=')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
                    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
                    "ExtensionName": "Com.Contoso.Referral",
                    "CompanyName": "Wingtip Toys",
                    "DealValue@odata.type": "#Int64",
                    "DealValue": 500050,
                    "ExpirationDate": "2015-12-03T10:00:00.000Z"
                }
            ]
        }
    ]
} 

Añadir o modificar datos en una extensión

Actualice una extensión con las propiedades del cuerpo de la solicitud:

• Si una propiedad del cuerpo de la solicitud coincide con el nombre de una propiedad existente en la extensión, se actualizan los datos de la extensión.
• De lo contrario, esa propiedad y sus datos se agregan a la extensión.

La extensión es un recurso que puede ser un mensaje, un evento de calendario o un contacto de Office 365 o Outlook.com. Se puede hacer referencia por nombre o ID, y de cualquier forma se devuelve la misma respuesta. Los datos en la carga útil de JSON pueden ser tipos primitivos o matrices de tipos primitivos.

PATCH https://outlook.office.com/api/beta/me/messages('{message_id}')/extensions('{extensionId}')
PATCH https://outlook.office.com/api/beta/me/events('{event_id}')/extensions('{extensionId}')
PATCH https://outlook.office.com/api/beta/me/contacts('{contact_id}')/extensions('{extensionId}')

Ámbito mínimo necesario

Uno de los siguientes ámbitos de lectura y escritura correspondiente al recurso de destino:

• https://outlook.office.com/mail.readwrite
• https://outlook.office.com/calendars.readwrite
• https://outlook.office.com/contacts.readwrite
• wl.imap
• wl.calendars_update
• wl.events_create
• wl.contacts_create

Parámetro	Tipo	Descripción
Parámetro URL
extensionId	cadena	Esto puede ser un nombre de extensión que sea un identificador de texto único entre todas las extensiones de una instancia de recurso, o un nombre completo que concatena el tipo de extensión y el identificador de texto único. El nombre completo se devuelve en la propiedad id cuando crea la extensión. Necesario.
Parámetros de cuerpo
ExtensionName	cadena	Identificador de texto único para una extensión. Necesario.

Solicitud de muestra

Cada uno de los dos ejemplos en esta sección utiliza la extensión en el ejemplo de exensión GET de arriba. El primero hace referencia a la extensión por nombre y, el segundo, a la extensión por ID. Sus cuerpos de solicitud y respuestas son iguales.

En cada ejemplo, se actualiza la extensión de arriba de estas formas:

• Cambiar CompanyName de Wingtip Toys a Wingtip Toys (USA)
• Cambiar DealValue de 500050 a 500100
• Agregar nuevos datos como la propiedad personalizada Updated

En este ejemplo, se hace referencia a la extensión por su nombre:

PATCH https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions('Com.Contoso.Referral')

Content-Type: application/json

{
    "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": "500100",
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "Updated": "2015-10-29T11:00:00.000Z"
} 

En este ejemplo, se hace referencia a la extensión por su ID (nombre completo):

PATCH https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Content-Type: application/json

{
    "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": "500100",
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "Updated": "2015-10-29T11:00:00.000Z"
} 

Respuesta de muestra

Una respuesta exitosa se indica en un código de respuesta HTTP 200 OK, y la extensión actualizada en el cuerpo de respuesta.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": 500100,
    "ExpirationDate": "2015-12-03T10:00:00Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

Eliminar una extensión

Elimine una extensión de la instancia especificada de un recurso. El recurso puede ser un mensaje, un evento de calendario o un contacto de Office 365 o Outlook.com.

Para eliminar una extensión en una instancia de cada uno de los recursos compatibles:

DELETE https://outlook.office.com/api/beta/me/messages('{message_id}')/extensions('{extension_name}')
DELETE https://outlook.office.com/api/beta/me/events('{event_id}')/extensions('{extension_name}')
DELETE https://outlook.office.com/api/beta/me/contacts('{contact_id}')/extensions('{extension_name}')

Ámbito mínimo necesario

Uno de los siguientes ámbitos de lectura y escritura correspondiente al recurso de destino:

• https://outlook.office.com/mail.readwrite
• https://outlook.office.com/calendars.readwrite
• https://outlook.office.com/contacts.readwrite
• wl.imap
• wl.calendars_update
• wl.events_create
• wl.contacts_create

Parámetro	Tipo	Descripción
Parámetros de dirección URL
extension_name	cadena	Identificador de texto único para una extensión. Necesario.

Solicitud de muestra

En el primer ejemplo, se hace referencia a una extensión por su nombre y se elimina la extensión en el mensaje especificado.

DELETE https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Com.Contoso.Referral')

Respuesta de muestra

Una respuesta correcta se indica mediante un código de respuesta HTTP 204 No Content.

Entidades de extensión

Extensión

Tipo: Microsoft.OutlookServices.Entity

Una entidad abstracta con la entidad Entity como tipo base.

OpenTypeExtension

Tipo: Microsoft.OutlookServices.Extension

Tipo abierto y abstracto de OData v4 que admite las propiedades y datos de especificación dinámica en una carga útil de JSON para actualizar una instancia de un tipo de entidad.

Propiedad	Tipo	Descripción	¿Se puede escribir?	¿Se puede filtrar?
ExtensionName	cadena	Nombre de extensión único. Use un sistema de nombre de dominio inverso basado en su propio dominio, por ejemplo, Com.Contoso.Contact.	Sí	No

Pasos siguientes

Tanto si está listo para empezar a compilar una aplicación como si simplemente desea obtener más información, tenemos todo lo que necesita.

• Comience con las API REST de correo, calendario y contactos.
• ¿Desea ver ejemplos? Los tenemos.

O bien, obtenga más información sobre el uso de la plataforma de Office 365:

• API REST de Outlook en el Centro de desarrollo de Outlook
• Información general del desarrollo en la plataforma de Office 365
• Autenticación de aplicaciones y autorización de recursos de Office 365
• Registre manualmente su aplicación con Azure AD para poder acceder a las API de Office 365
• Referencia de las API REST de correo
• Referencia de las API de REST de calendario
• Referencia de las API de REST de contactos
• API REST de tareas (vista previa)
• Referencia de recursos para las API de REST de correo, calendario, contactos y tareas