Referencia de la API de REST de propiedades extendidas de Outlook (versión 2.0)

Artículo
06/30/2018

La API de REST de propiedades extendidas de Outlook permite a las aplicaciones almacenar datos personalizados y les proporciona un mecanismo Fallback para acceder a datos personalizados de propiedades MAPI de Outlook cuando estas propiedades ya no están expuestas en los metadatos de la API de REST de Outlook. Puede usar la API de propiedades extendidas para almacenar u obtener dichos datos personalizados en un mensaje, carpeta de correo, evento, calendario, contacto, carpeta de contactos, tarea o carpeta de tareas de la cuenta de usuario que ha iniciado sesión. 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 simplificar 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 2.0 de la API? En el índice de la izquierda, vaya a la sección Referencia de la API de REST de Office 365 y seleccione la versión que desee.

Usar la API de REST de propiedades extendidas

¿Propiedades extendidas o extensiones de datos?

Utilice las propiedades extendidas y esta API de REST solo si necesita acceder a datos personalizados de las propiedades MAPI de Outlook que aún no estén expuestos a través de los metadatos de la API de REST de Outlook. En la mayoría de los escenarios, debe usar extensiones de datos de Office 365 y su API de REST para almacenar datos personalizados de elementos del buzón del usuario y acceder a ellos. 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 en cualquier otra API de REST de Outlook, debe incluir un token de acceso válido para cada solicitud a la API de propiedades extendidas. Obtener un token de acceso requiere haber 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 simplificadas para usted. Tenga esto en cuenta a medida que avance con las operaciones específicas de la API de propiedades extendidas.

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 de la API de REST de Outlook.

Recursos de REST admitidos

Puede crear propiedades extendidas para instancias de los siguientes recursos:

El recurso debe estar en el buzón del usuario conectado a Office 365 o Outlook.com.

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 dirección URL
calendar_id	cadena	Id. de calendario
contact_id	cadena	Id. de contacto.
contactFolder_id	cadena	Id. de carpeta de contactos.
event_id	cadena	Id. de evento.
mailFolder_id	cadena	Id. de carpeta de correo.
message_id	cadena	Id. de mensaje.
propertyId_value	cadena	Un valor PropertyId en alguno de los formatos admitidos.
property_value	cadena	El valor de una propiedad extendida.
task_id	cadena	Id. de tarea.
taskFolder_id	cadena	Id. de carpeta de tareas.

Consulte Utilizar la API de REST de Outlook para obtener más información común a todos los subconjuntos de esa API.

Información general

Puede crear y almacenar datos dinámicamente en una propiedad extendida de una instancia de la entidad. Dependiendo de si pretende almacenar un único valor o múltiples valores (del mismo tipo), puede crear la propiedad extendida como una SingleValueLegacyExtendedProperty o una MultiValueLegacyExtendedProperty.

Cada uno de esos tipos identifica la propiedad por su PropertyId y almacena datos en Value.

Puede utilizar el PropertyId para obtener una instancia de la entidad específica junto con esa propiedad extendida, o filtrar una propiedad extendida de valor único para obtener todas las instancias que tengan esa propiedad.

Nota

No puede utilizar la API de REST para obtener todas las propiedades extendidas de una instancia específica en una llamada.

Formatos de PropertyId

Al crear una propiedad extendida de valor único o con múltiples valores, puede especificar su PropertyId en uno de los dos formatos, mediante un nombre de cadena o bien con un identificador numérico, y en el tipo real del valor o valores de la propiedad. En las siguientes dos tablas se describen los formatos compatibles para especificar propiedades extendidas de valor único y con múltiples valores. {_type_} representa el tipo de valor o valores de la propiedad. Lo que se muestra en los ejemplos son la cadena, el número entero y las matrices de esos tipos.

Por simplicidad, y dado que las propiedades extendidas interoperan en la mayoría de los casos con propiedades MAPI definidas que no están expuestas en los metadatos de la API de REST de Outlook, el formato que elija debe reflejar si la propiedad MAPI correspondiente usa una cadena de caracteres o un valor numérico en su identificador de propiedad MAPI. En [MS-OXPROPS] Microsoft Corporation, Lista de las propiedades maestras de los protocolos de Exchange Server, encontrará la información que necesita para asignar una propiedad extendida a una propiedad MAPI existente, como el identificador de la propiedad o el GUID.

Nota

Tras elegir un formato para el PropertyId, deberá acceder a la propiedad extendida usando solo ese formato.

Formatos de PropertyId válidos para propiedades extendidas de valor único

Formato	Ejemplo	Descripción
“{type} {guid} Nombre {name}”	`"String {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty"`	Identifica una propiedad mediante el espacio de nombres (GUID) al que pertenece y mediante un nombre.
“{type} {guid} Id. {id}”	`"Integer {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8012"`	Identifica una propiedad mediante el espacio de nombres (GUID) al que pertenece y mediante un identificador.

Formatos de PropertyId válidos para propiedades extendidas con múltiples valores

Formato	Ejemplo	Descripción
“{type} {guid} Nombre {name}”	`"StringArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty"`	Identifica una propiedad mediante un espacio de nombres (GUID) y un nombre.
“{type} {guid} Id. {id}”	`"IntegerArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8013"`	Identifica una propiedad mediante un espacio de nombres (GUID) y un identificador.

Operaciones de propiedad extendida

Crear una propiedad extendida en un elemento existente
Crear una propiedad extendida en un nuevo elemento
Extender el elemento con la propiedad extendida
Filtro para una propiedad extendida de valor único

Crear una propiedad extendida en un elemento existente

Cree una o más propiedades extendidas para la instancia especificada de un recurso compatible. Cada propiedad extendida puede ser de un solo valor o tener múltiples valores.

PATCH https://outlook.office.com/api/v2.0/me/messages('{message_id}')
PATCH https://outlook.office.com/api/v2.0/me/events('{event_id}')
PATCH https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')
PATCH https://outlook.office.com/api/v2.0/me/tasks('{task_id}')
PATCH https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')
PATCH https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')
PATCH https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')
PATCH https://outlook.office.com/api/v2.0/me/taskfolders('{taskFolder_id}')

Á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
https://outlook.office.com/tasks.readwrite
wl.imap
wl.calendars_update
wl.events_create
wl.contacts_create

Parámetro	Tipo	Descripción
Parámetros de cuerpo
SingleValueExtendedProperties	Colección (SingleValueLegacyExtendedProperty)	Una matriz de una o varias propiedades extendidas de valor único.
PropertyId	cadena	Especifique esto para cada propiedad de la colección SingleValueExtendedProperties con el fin de identificar la propiedad. Debe estar conforme a alguno de los formatos compatibles para propiedades extendidas de valor único. Obligatorio.
Valor	cadena	Especifique el valor de propiedad para cada propiedad de la colección SingleValueExtendedProperties. Obligatorio.
MultiValueExtendedProperties	Colección (MultiValueLegacyExtendedProperty)	Una matriz de una o más propiedades extendidas con varios valores.
PropertyId	cadena	Especifique esto para cada propiedad de la colección MultiValueExtendedProperties con el fin de identificar la propiedad. Debe estar conforme a alguno de los formatos compatibles para propiedades extendidas de múltiples valores. Obligatorio.
Valor	Colección (cadena)	Especifique los valores de la propiedad para cada propiedad de la colección MultiValueExtendedProperties. Obligatorio.

Solicitud de muestra

El primer ejemplo crea una propiedad extendida de valor único para el mensaje especificado. Esa propiedad extendida es el único elemento de la matriz SingleValueExtendedProperties. El cuerpo de la solicitud incluye lo siguiente en relación con la propiedad extendida:

PropertyId especifica el tipo de propiedad como string, el GUID y la propiedad denominada Color.
Value especifica Green como el valor de la propiedad Color.

PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')

Content-Type: application/json

{
  "SingleValueExtendedProperties": [
      {
         "PropertyId":"String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
         "Value":"Green"
      }
    ]
}

Respuesta de muestra

Una respuesta correcta se indica mediante un código de respuesta HTTP 200 OK e incluye el mensaje especificado en el cuerpo de la respuesta. Es similar a la respuesta al actualizar un mensaje. El cuerpo de la respuesta no incluye la propiedad extendida recién creada.

Solicitud de muestra

El segundo ejemplo crea una propiedad extendida de múltiples valores para el mensaje especificado. Esa propiedad es el único elemento de la matriz MultiValueExtendedProperties. El cuerpo de la solicitud incluye:

PropertyId, que define la propiedad como una matriz de cadenas con el GUID especificado y el nombre Palette.
Value, que define Palette como una matriz de tres valores de cadena, ["Green", "Aqua", "Blue"].

PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2_as77AACHsLrBBBA=')

Content-Type: application/json

{
  "MultiValueExtendedProperties": [
      {
         "PropertyId":"StringArray {66f5a359-4659-4830-9070-00049ec6ac6e} Name Palette",
         "Value":["Green", "Aqua", "Blue"]
      }
    ]
}

Respuesta de muestra

Para ver la propiedad extendida recién creada, expanda el mensaje con la propiedad extendida.

Crear una propiedad extendida en un nuevo elemento

Cree una o más propiedades extendidas al tiempo que crea una nueva instancia de un recurso compatible; todo ello en la misma llamada POST. Incluya la propiedad o propiedades extendidas en el cuerpo de la solicitud POST.

POST https://outlook.office.com/api/v2.0/me/messages
POST https://outlook.office.com/api/v2.0/me/events
POST https://outlook.office.com/api/v2.0/me/contacts
POST https://outlook.office.com/api/v2.0/me/tasks
POST https://outlook.office.com/api/v2.0/me/mailfolders
POST https://outlook.office.com/api/v2.0/me/calendars
POST https://outlook.office.com/api/v2.0/me/contactfolders
POST https://outlook.office.com/api/v2.0/me/taskfolders

Á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
https://outlook.office.com/tasks.readwrite
wl.imap
wl.calendars_update
wl.events_create
wl.contacts_create

Parámetro	Tipo	Descripción
Parámetros de cuerpo
SingleValueExtendedProperties	Colección (SingleValueLegacyExtendedProperty)	Una matriz de una o varias propiedades extendidas de valor único.
PropertyId	cadena	Especifique esto para cada propiedad de la colección SingleValueExtendedProperties con el fin de identificar la propiedad. Debe estar conforme a alguno de los formatos compatibles para propiedades extendidas de valor único. Obligatorio.
Valor	cadena	Especifique el valor de propiedad para cada propiedad de la colección SingleValueExtendedProperties. Obligatorio.
MultiValueExtendedProperties	Colección (MultiValueLegacyExtendedProperty)	Una matriz de una o más propiedades extendidas con varios valores.
PropertyId	cadena	Especifique esto para cada propiedad de la colección MultiValueExtendedProperties con el fin de identificar la propiedad. Debe estar conforme a alguno de los formatos compatibles para propiedades extendidas de múltiples valores. Obligatorio.
Valor	Colección (cadena)	Especifique los valores de la propiedad para cada propiedad de la colección MultiValueExtendedProperties. Obligatorio.

Solicitud de muestra

El primer ejemplo crea un nuevo evento y una propiedad extendida de valor único. Además de las propiedades que normalmente incluiría para un nuevo evento, el cuerpo de la solicitud incluye la matriz SingleValueExtendedProperties que contiene una propiedad extendida de valor único, y lo siguiente en relación con esa propiedad:

PropertyId especifica el tipo de propiedad como string, el GUID y la propiedad denominada Fun.
Value especifica Food como el valor de la propiedad Fun.

POST https://outlook.office.com/api/v2.0/me/events

Content-Type: application/json

{
  "Subject": "Celebrate Thanksgiving",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together!"
  },
  "Start": {
      "DateTime": "2015-11-26T18:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-26T23:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    }
  ],
  "SingleValueExtendedProperties": [
     {
           "PropertyId":"String {66f5a359-4659-4830-9070-00040ec6ac6e} Name Fun",
           "Value":"Food"
     }
  ]
}

Respuesta de muestra

Una respuesta correcta se indica mediante un código de respuesta HTTP 201 Created e incluye el nuevo evento en el cuerpo de la respuesta. Es similar a la respuesta al crear solo un evento. El cuerpo de la respuesta no incluye ninguna propiedad extendida recién creada.

Para ver la propiedad extendida recién creada, expanda el elemento con ella.

Solicitud de muestra

El segundo ejemplo crea una propiedad extendida de múltiples valores en un nuevo evento; todo ello en la misma operación POST. Además de las propiedades que normalmente incluiría para un nuevo evento, el cuerpo de la solicitud incluye la matriz MultiValueExtendedProperties que contiene una propiedad extendida.

El cuerpo de la solicitud incluye lo siguiente en relación con esa propiedad extendida de múltiples valores:

PropertyId, que define la propiedad como una matriz de cadenas con el GUID especificado y el nombre Recreation.
Value, que define Recreation como una matriz de tres valores de cadena, ["Food", "Hiking", "Swimming"].

POST https://outlook.office.com/api/v2.0/me/events

Content-Type: application/json

{
  "Subject": "Family reunion",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together this Thanksgiving!"
  },
  "Start": {
      "DateTime": "2015-11-26T09:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-29T21:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    },
    {
      "EmailAddress": {
        "Address": "Lauren@contoso.com",
        "Name": "Lauren Solis"
      },
      "Type": "Required"
    }
  ],
  "MultiValueExtendedProperties": [
     {
           "PropertyId":"StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
           "Value": ["Food", "Hiking", "Swimming"]
     }
  ]
}

Respuesta de muestra

Para ver la propiedad extendida recién creada, expanda el elemento con ella.

Expandir el elemento con la propiedad extendida

Expanda una instancia de un recurso compatible con la propiedad extendida que se especifica mediante un filtro en el PropertyId.

La cadena {propertyId_value} que especifique en el filtro de PropertyId debe estar conforme a alguno de los formatos admitidos de PropertyId. Asegúrese de aplicar la codificación de URL a los caracteres de espacio de la cadena de filtro.

Expandir el elemento con propiedades extendidas de valor único que coincidan

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/events('{event_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/tasks('{task_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/taskfolders('{taskfolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

Expandir el elemento con propiedades extendidas de múltiples valores que coincidan

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/events('{event_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/tasks('{task_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/taskfolders('{taskfolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

Á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
https://outlook.office.com/tasks.read
wl.imap
wl.calendars
wl.contacts_calendars
wl.basic

Solicitud de muestra

El primer ejemplo obtiene y expande el mensaje especificado incluyendo una propiedad extendida de valor único. El filtro devuelve la propiedad extendida cuyo PropertyId coincide con la cadena String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color (se ha quitado aquí la codificación de URL para facilitar la lectura).

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')?$expand=SingleValueExtendedProperties($filter=PropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color')

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 devuelve la propiedad extendida del filtro.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGE1M2_bs88AACHsLqWAAA=')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H\"",
    "Id": "AAMkAGE1M2_bs88AACHsLqWAAA=",
    "CreatedDateTime": "2015-11-11T02:41:24Z",
    "LastModifiedDateTime": "2015-12-09T04:07:57Z",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H",
    "Categories": [
    ],
    "ReceivedDateTime": "2015-11-11T02:41:24Z",
    "SentDateTime": "2015-11-11T02:41:24Z",
    "HasAttachments": false,
    "InternetMessageId": "<SN2SR0101MB002977E7C30F9CA9AA55961484130@SN2SR0101MB0029.contoso.com>",
    "Subject": "RE: Talk about emergency prep",
    "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=iso-8859-1\">\r\n<style type=\"text/css\" style=\"\">\r\n<!--\r\np\r\n\t{margin-top:0;\r\n\tmargin-bottom:0}\r\n-->\r\n</style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<hr tabindex=\"-1\" style=\"display:inline-block; width:98%\">\r\n<div id=\"divRplyFwdMsg\" dir=\"ltr\"><font face=\"Calibri, sans-serif\" color=\"#000000\" style=\"font-size:11pt\"><b>From:</b> Christine Irwin<br>\r\n<b>Sent:</b> Sunday, November 8, 2015 12:28:31 AM<br>\r\n<b>To:</b> Terrie Barrera<br>\r\n<b>Subject:</b> Talk about emergency prep<br>\r\n<b>When:</b> Sunday, November 8, 2015 7:00 PM-8:00 PM.<br>\r\n<b>Where:</b> The Commons</font>\r\n<div>&nbsp;</div>\r\n</div>\r\n<div>\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt; color:#000000; background-color:#FFFFFF; font-family:Calibri,Arial,Helvetica,sans-serif\">\r\n<p>Please see the attached before you come to the meeting.<br>\r\n</p>\r\n</div>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "________________________________",
    "Importance": "Normal",
    "ParentFolderId": "AQMkAGE1M2jgxCloXP1JupQN7j5uzzwAAAIBDwAAAA==",
    "Sender": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "From": null,
    "ToRecipients": [
        {
            "EmailAddress": {
                "Name": "Christine Irwin",
                "Address": "christine@contoso.com"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVlLTY0YjcxZWUzNTE1MAAQAHWT1sRiMChEmlQCIZUadoU=",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsRead": true,
    "IsDraft": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACHsLqWAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "HashtagDetailsPreview": null,
    "LikesPreview": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "UnsubscribeData": [
    ],
    "UnsubscribeEnabled": false,
    "SingleValueExtendedProperties@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2_bs88AACHsLqWAAA%3D')/SingleValueExtendedProperties",
    "SingleValueExtendedProperties": [
        {
            "PropertyId": "String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
            "Value": "Green"
        }
    ]
}

Solicitud de muestra

El segundo ejemplo obtiene y expande el evento especificado incluyendo una propiedad extendida de múltiples valores. El filtro devuelve la propiedad extendida cuyo PropertyId coincide con la cadena StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation (se ha quitado aquí la codificación de URL para facilitar la lectura).

GET https://outlook.office.com/api/v2.0/me/events('AAMkAGE1M2_bs88AACbuFiiAAA=')?$expand=MultiValueExtendedProperties($filter=PropertyId%20eq%20'StringArray%20{66f5a359-4659-4830-9070-00050ec6ac6e}%20Name%20Recreation')

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 evento especificado y devuelve la propiedad extendida del filtro.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Events/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE1M2_bs88AACbuFiiAAA=')",
    "@odata.etag": "W/\"mODEKWhc/Um6lA3uPm7PPAAAm8k15A==\"",
    "Id": "AAMkAGE1M2_bs88AACbuFiiAAA=",
    "CreatedDateTime": "2015-12-09T05:18:05.9477979Z",
    "LastModifiedDateTime": "2015-12-09T05:18:06.197802Z",
    "ChangeKey": "mODEKWhc/Um6lA3uPm7PPAAAm8k15A==",
    "Categories": [
    ],
    "OriginalStartTimeZone": "Pacific Standard Time",
    "OriginalEndTimeZone": "Pacific Standard Time",
    "ResponseStatus": {
        "Response": "Organizer",
        "Time": "0001-01-01T00:00:00Z"
    },
    "iCalUId": "04000000828A332796D9",
    "ReminderMinutesBeforeStart": 15,
    "IsReminderOn": true,
    "HasAttachments": false,
    "Subject": "Family reunion",
    "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\nLet's get together this Thanksgiving!\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "Let's get together this Thanksgiving!",
    "Importance": "Normal",
    "Sensitivity": "Normal",
    "Start": {
        "DateTime": "2015-11-26T17:00:00.0000000",
        "TimeZone": "UTC"
    },
    "End": {
        "DateTime": "2015-11-30T05:00:00.0000000",
        "TimeZone": "UTC"
    },
    "Location": {
        "DisplayName": ""
    },
    "IsAllDay": false,
    "IsCancelled": false,
    "IsOrganizer": true,
    "Recurrence": null,
    "ResponseRequested": true,
    "SeriesMasterId": null,
    "ShowAs": "Busy",
    "Type": "SingleInstance",
    "Attendees": [
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Terrie Barrera",
                "Address": "Terrie@contoso.com"
            }
        },
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Lauren Solis",
                "Address": "Lauren@contoso.com"
            }
        }
    ],
    "Organizer": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACbuFiiAAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
    "MultiValueExtendedProperties@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Events('AAMkAGE1M2_bs88AACbuFiiAAA%3D')/MultiValueExtendedProperties",
    "MultiValueExtendedProperties": [
        {
            "PropertyId": "StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
            "Value": [
                "Food",
                "Hiking",
                "Swimming"
            ]
        }
    ]
}

Obtener un elemento filtrando según la propiedad extendida

Obtenga instancias de un recurso compatible que tenga la propiedad extendida especificada por un filtro de PropertyId y Value. El filtro se aplica a todas las instancias del recurso en el buzón del usuario que inició sesión. Este filtrado solo admite propiedades extendidas de valor único; no de múltiples valores.

La cadena {propertyId_value} que especifique en el filtro de PropertyId debe estar conforme a alguno de los formatos admitidos de PropertyId.

Si {property_value} no es una cadena, asegúrese de que se convierte explícitamente ep/value para el tipo de datos Edm adecuado cuando se compara con {property_value}. Vea a continuación solicitudes de muestra de propiedades que no sean de cadena para ejemplos de tales conversiones.

Asegúrese de aplicar la codificación de URL a los siguientes caracteres de la cadena de filtro: dos puntos, barra diagonal y espacio.

GET https://outlook.office.com/api/v2.0/me/messages?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/events?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/contacts?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/tasks?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/mailfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/calendars?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/contactfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/taskfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

Á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
https://outlook.office.com/tasks.read
wl.imap
wl.calendars
wl.contacts_calendars
wl.basic

Solicitud de muestra

El primer ejemplo obtiene mensajes que tengan la propiedad extendida de valor único que especifica el filtro. El filtro devuelve la propiedad extendida que tenga lo siguiente:

Un PropertyId que coincida con la cadena String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color (se ha quitado aquí la codificación de URL para facilitar la lectura).
Un Value que sea Green.

GET https://outlook.office.com/api/v2.0/Me/Messages?$filter=SingleValueExtendedProperties%2FAny(ep%3A%20ep%2FPropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color'%20and%20ep%2FValue%20eq%20'Green')

Los siguientes dos ejemplos muestran cómo obtener mensajes que tengan propiedades extendidas de valor único que no sean de tipo cadena. Para facilitar la lectura, no incluyen la codificación de direcciones URL necesaria. En el siguiente ejemplo, se muestra un filtro que busca una propiedad extendida que tenga lo siguiente:

Un PropertyId que coincida con la cadena CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid.
Un Value que sea el GUID b9cf8971-7d55-4b73-9ffa-a584611b600b. Para comparar el valor de propiedad con un GUID, convierta ep/Value en Edm.Guid.

GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid' and cast(ep/Value, Edm.Guid) eq (b9cf8971-7d55-4b73-9ffa-a584611b600b))

El tercer y último ejemplo muestra un filtro que busca la propiedad extendida que tenga lo siguiente:

Un PropertyId que coincida con la cadena Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete.
Un Value igual al número entero 12. Para comparar el valor de propiedad con un número entero, convierta ep/Value en Edm.Int32.

GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete' and cast(ep/Value, Edm.Int32) eq 12)

Respuesta de muestra

Una respuesta correcta se indica mediante un código de respuesta HTTP 200 OK, y el cuerpo de la respuesta incluye todas las propiedades de los mensajes cuya propiedad extendida coincida con el filtro correspondiente. El cuerpo de la respuesta es similar a la respuesta de la obtención de una colección de mensajes. El cuerpo de la respuesta no incluye la propiedad extendida coincidente.

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:

Compartir a través de

Referencia de la API de REST de propiedades extendidas de Outlook (versión 2.0)

Usar la API de REST de propiedades extendidas

¿Propiedades extendidas o extensiones de datos?

Autenticación

Versión de la API

Recursos de REST admitidos

Parámetros de dirección URL

Información general

Formatos de PropertyId

Operaciones de propiedad extendida

Crear una propiedad extendida en un elemento existente

Ámbito mínimo necesario

Solicitud de muestra

Respuesta de muestra

Solicitud de muestra

Respuesta de muestra

Crear una propiedad extendida en un nuevo elemento

Ámbito mínimo necesario

Solicitud de muestra

Respuesta de muestra

Solicitud de muestra

Respuesta de muestra

Expandir el elemento con la propiedad extendida

Expandir el elemento con propiedades extendidas de valor único que coincidan

Expandir el elemento con propiedades extendidas de múltiples valores que coincidan

Ámbito mínimo necesario

Solicitud de muestra

Respuesta de muestra

Solicitud de muestra

Respuesta de muestra

Obtener un elemento filtrando según la propiedad extendida

Ámbito mínimo necesario

Solicitud de muestra

Respuesta de muestra

Pasos siguientes

Recursos adicionales