Creación de openTypeExtension

  • Artículo

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

Precaución

Las aplicaciones existentes que usan esta característica con baseTask o baseTaskList deben actualizarse, ya que el conjunto de API de tareas pendientes basado en estos recursos está en desuso a partir del 31 de mayo de 2022. Ese conjunto de API dejará de devolver datos el 31 de agosto de 2022. Use el conjunto de API basado en todoTask.

Cree una extensión abierta (objeto openTypeExtension) y agregue propiedades personalizadas en una instancia nueva o existente de un recurso. Puede crear una extensión abierta en una instancia de recurso y almacenar datos personalizados en ella en la misma operación, excepto para recursos específicos.

La tabla de la sección Permisos enumera los recursos que admiten extensiones abiertas.

Nota: si está creando extensiones abiertas en recursos de Outlook, consulte consideraciones específicas de Outlook en tipo de recurso openTypeExtension.

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet
✅ ✅ ✅ ✅

Permisos

Según la extensión del recurso que está creando y el tipo de permiso (delegado o de aplicación) solicitado, el permiso especificado en la tabla siguiente es el menos privilegiado necesario para llamar a esta API. Para más información, incluida la toma de precauciones antes de elegir permisos con más privilegios, busque los siguientes permisos en Permisos.

Recurso admitido Delegado (cuenta profesional o educativa) Delegado (cuenta de Microsoft personal) Aplicación
dispositivo Directory.AccessAsUser.All No admitido Device.ReadWrite.All
evento Calendars.ReadWrite Calendars.ReadWrite Calendars.ReadWrite
grupo Group.ReadWrite.All No admitido Group.ReadWrite.All
evento de grupo Group.ReadWrite.All No admitido No admitido
publicación de grupo Group.ReadWrite.All No admitido Group.ReadWrite.All
mensaje Mail.ReadWrite Mail.ReadWrite Mail.ReadWrite
organization Organization.ReadWrite.All No se admite Organization.ReadWrite.All
contacto personal Contacts.ReadWrite Contacts.ReadWrite Contacts.ReadWrite
todoTask Tasks.ReadWrite Tasks.ReadWrite No compatible
todoTaskList Tasks.ReadWrite Tasks.ReadWrite No compatible
user User.ReadWrite User.ReadWrite User.ReadWrite.All
baseTask (en desuso) Tasks.ReadWrite Tasks.ReadWrite No compatible
baseTaskList (en desuso) Tasks.ReadWrite Tasks.ReadWrite No compatible

Solicitud HTTP

Crear una extensión en una instancia de recurso nueva

Usar la misma solicitud REST que se usa para crear la instancia.

POST /users/{userId|userPrincipalName}/events
POST /users/{userId|userPrincipalName}/messages
POST /groups/{userId}/events
POST /groups/{userId}/threads/{threadId}/posts/{postId}/reply
POST /users/{userId|userPrincipalName}/contacts
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/tasks
POST /users/{userId|userPrincipalName}/todo/lists
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/tasks
POST /users/{userId|userPrincipalName}/tasks/lists

Nota: Esta sintaxis muestra algunas maneras comunes para crear las instancias de recursos admitidos. Todas las otras formas de sintaxis POST que le permiten crear estas instancias de recursos admiten la creación de extensiones abiertas en ellas de una manera similar.

Consulte la sección Cuerpo de la solicitud para obtener información sobre cómo incluir las propiedades de la nueva instancia de recurso y la extensión en el cuerpo de la solicitud.

Crear una extensión en una instancia de recurso existente

Identifique la instancia del recurso en la solicitud y haga una POST a la propiedad de navegación extensions.

POST /administrativeunits/{administrativeUnitId}/extensions
POST /devices/{deviceId}/extensions
POST /users/{userId|userPrincipalName}/events/{eventId}/extensions
POST /groups/{groupId}/extensions
POST /groups/{groupId}/events/{eventId}/extensions
POST /groups/{groupId}/threads/{threadId}/posts/{postId}/extensions
POST /users/{userId|userPrincipalName}/messages/{messageId}/extensions
POST /organization/{organizationId}/extensions
POST /users/{userId|userPrincipalName}/contacts/{contactId}/extensions
POST /users/{userId|userPrincipalName}/extensions
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/tasks/{taskId}/extensions
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/extensions
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/tasks/{taskId}/extensions
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/extensions

Nota: Esta sintaxis anterior muestra algunas formas comunes para identificar una instancia del recurso, con el fin de crear una extensión en él. Todas las otras formas de sintaxis que le permiten identificar estas instancias de recursos admiten la creación de extensiones abiertas en ellas de una manera similar.

Consulte la sección Cuerpo de la solicitud para obtener información sobre cómo incluir la extensión en el cuerpo de la solicitud.

Encabezados de solicitud

Nombre Valor
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.
Content-Type application/json

Cuerpo de la solicitud

Proporcione un cuerpo JSON de openTypeExtension, con los siguientes pares nombre-valor necesarios y cualquier dato personalizado adicional. Los datos de la carga JSON pueden ser de tipo primitivo o matrices de tipo primitivo.

Nombre Valor
@odata.type Microsoft.Graph.OpenTypeExtension
extensionName Cadena única

Al crear una extensión en una instancia de recurso nueva, además del nuevo objeto openTypeExtension, proporcione una representación JSON de las propiedades relevantes para crear esa instancia de recurso.

Respuesta

Código de respuesta

Dependiendo de la operación, el código de respuesta puede ser 201 Created o 202 Accepted.

Cuando se crea una extensión con la misma operación que se usa para crear una instancia de recursos, la operación devuelve el mismo código de respuesta que devuelve cuando se usa la operación para crear la instancia de recursos sin la extensión. Consulte los temas correspondientes para crear la instancia, como se muestra arriba.

Cuerpo de la respuesta

Escenario Recurso Cuerpo de la respuesta
Crear una extensión al crear explícitamente una nueva instancia de recursos contacto, evento, mensaje Incluye la nueva instancia ampliada con el objeto openTypeExtension.
Crear una extensión al crear implícitamente una instancia de recursos post La respuesta incluye sólo un código de respuesta, pero no un cuerpo de respuesta.
Crear una extensión en una instancia de recurso existente Todos los recursos admitidos Incluye el objeto openTypeExtension.

Ejemplo

Solicitud 1

El primer ejemplo crea un mensaje y una extensión en la misma llamada. El cuerpo de la solicitud incluye:

  • Las propiedades subject, body y toRecipients típicas de un nuevo mensaje.

  • Y en cuanto a la extensión:

    • El tipo microsoft.graph.openTypeExtension.
    • El nombre de la extensión "Com.Contoso.Referral".
    • Los datos adicionales se almacenan como tres propiedades personalizadas en la carga JSON: companyName, expirationDate y dealValue.
POST https://graph.microsoft.com/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.graph.openTypeExtension",
      "extensionName": "Com.Contoso.Referral",
      "companyName": "Wingtip Toys",
      "expirationDate": "2015-12-30T11:00:00.000Z",
      "dealValue": 10000
    }
  ]
}

Respuesta 1

Aquí tiene la respuesta del primer ejemplo. 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.graph.openTypeExtension.Com.Contoso.Referral.
  • La propiedad predeterminada extensionName especificada en la solicitud.
  • Los datos personalizados especificados en la solicitud y almacenados como 3 propiedades personalizadas.

Nota: el objeto de respuesta que se muestra aquí puede haberse acortado para mejorar la legibilidad.

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#Me/messages/$entity",
  "@odata.id": "https://graph.microsoft.com/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",
  "inferenceClassification": "Focused",
  "extensions": [
    {
      "@odata.type": "#microsoft.graph.openTypeExtension",
      "@odata.id": "https://graph.microsoft.com/beta/users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/messages
('AAMkAGEbs88AAB84uLuAAA=')/extensions('microsoft.graph.openTypeExtension.Com.Contoso.Referral')",
      "id": "microsoft.graph.openTypeExtension.Com.Contoso.Referral",
      "extensionName": "Com.Contoso.Referral",
      "companyName": "Wingtip Toys",
      "expirationDate": "2015-12-30T11:00:00.000Z",
      "dealValue": 10000
    }
  ]
}

Solicitud 2

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

  • El tipo microsoft.graph.openTypeExtension.
  • El nombre de la extensión "Com.Contoso.Referral".
  • Los datos adicionales se almacenan como 3 propiedades personalizadas en la carga JSON: companyName, dealValue y expirationDate.
POST https://graph.microsoft.com/beta/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions
Content-Type: application/json

{
  "@odata.type" : "microsoft.graph.openTypeExtension",
  "extensionName" : "Com.Contoso.Referral",
  "companyName" : "Wingtip Toys",
  "dealValue" : 500050,
  "expirationDate" : "2015-12-03T10:00:00.000Z"
}

Respuesta 2

Aquí tiene la respuesta del segundo ejemplo. El cuerpo de la respuesta incluye lo siguiente para la nueva extensión:

  • La propiedad predeterminada extensionName.
  • La propiedad id con el nombre completo microsoft.graph.openTypeExtension.Com.Contoso.Referral.
  • Los datos personalizados que se almacenarán.
HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#Me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "@odata.id": "https://graph.microsoft.com/beta/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('microsoft.graph.openTypeExtension.Com.Contoso.Referral')",
    "extensionName": "Com.Contoso.Referral",
    "id": "microsoft.graph.openTypeExtension.Com.Contoso.Referral",
    "companyName": "Wingtip Toys",
    "dealValue": 500050,
    "expirationDate": "2015-12-03T10:00:00.000Z"
}

Solicitud 3

El tercer ejemplo crea una extensión en el evento de grupo especificado. El cuerpo de la solicitud incluye lo siguiente para la extensión:

  • El tipo microsoft.graph.openTypeExtension.
  • El nombre de la extensión "Com.Contoso.Deal".
  • Los datos adicionales se almacenan como 3 propiedades personalizadas en la carga JSON: companyName, dealValue y expirationDate.
POST https://graph.microsoft.com/beta/groups/f5480dfd-7d77-4d0b-ba2e-3391953cc74a/events/AAMkADVl17IsAAA=/extensions
Content-type: application/json

{
  "@odata.type" : "microsoft.graph.openTypeExtension",
  "extensionName" : "Com.Contoso.Deal",
  "companyName" : "Alpine Skis",
  "dealValue" : 1010100,
  "expirationDate" : "2015-07-03T13:04:00.000Z"
}

Respuesta 3

Aquí tiene la respuesta del tercer ejemplo de solicitud.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups('f5480dfd-7d77-4d0b-ba2e-3391953cc74a')/events('AAMkADVl7IsAAA%3D')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "id": "microsoft.graph.openTypeExtension.Com.Contoso.Deal",
    "extensionName": "Com.Contoso.Deal",
    "companyName": "Alpine Skis",
    "dealValue": 1010100,
    "expirationDate": "2015-07-03T13:04:00Z"
}

Solicitud 4

El cuarto ejemplo crea una extensión en una nueva publicación de grupo mediante la misma llamada de acción de respuesta a una publicación de grupo existente. La acción de respuesta crea una nueva publicación y una nueva extensión insertada en la publicación. El cuerpo de la solicitud contiene una propiedad post que, a su vez, contiene el cuerpo de la nueva publicación y los siguientes datos de la nueva extensión:

  • El tipo microsoft.graph.openTypeExtension.
  • El nombre de la extensión "Com.Contoso.HR".
  • Los datos adicionales se almacenan como 3 propiedades personalizadas en la carga JSON: companyName, expirationDate y la matriz de cadenas topPicks.
POST https://graph.microsoft.com/beta/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/threads/AAQkADJizZJpEWwqDHsEpV_KA==/posts/AAMkADJiUg96QZUkA-ICwMubAAC1heiSAAA=/reply
Content-type: application/json

{
  "post": {
    "body": {
      "contentType": "html",
      "content": "<html><body><div><div><div><div>When and where? </div></div></div></div></body></html>"
    },
  "extensions": [
    {
      "@odata.type": "microsoft.graph.openTypeExtension",
      "extensionName": "Com.Contoso.HR",
      "companyName": "Contoso",
      "expirationDate": "2015-07-03T13:04:00.000Z",
      "topPicks": [
        "Employees only",
        "Add spouse or guest",
        "Add family"
      ]
    }
  ]
  }
}

Respuesta 4

Aquí tiene la respuesta del cuarto ejemplo. Si se crea correctamente una extensión en una nueva publicación de grupo, el resultado es solo el código de respuesta HTTP 202.

HTTP/1.1 202 Accepted
Content-type: text/plain
Content-Length: 0

Solicitud 5

El quinto ejemplo crea una extensión en una nueva publicación de grupo mediante la misma operación POST que para crear una conversación. La operación POST crea una nueva conversación, un nuevo hilo, una nueva publicación e inserta una nueva extensión en la publicación. El cuerpo de la solicitud incluye las propiedades Topic y Threads y un objeto post de elemento secundario para la nueva conversación. El objeto post contiene a su vez el cuerpo de la nueva publicación y los siguientes datos de la extensión:

  • El tipo microsoft.graph.openTypeExtension.
  • El nombre de la extensión "Com.Contoso.HR".
  • Los datos adicionales se almacenan como 3 propiedades personalizadas en la carga JSON: companyName, expirationDate y la matriz de cadenas topPicks.
POST https://graph.microsoft.com/beta/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/conversations
Content-type: application/json

{
  "Topic": "Does anyone have a second?",
  "Threads": [
    {
      "Posts": [
        {
          "Body": {
            "ContentType": "HTML",
            "Content": "This is urgent!"
          },
          "Extensions": [
            {
              "@odata.type": "microsoft.graph.openTypeExtension",
              "extensionName": "Com.Contoso.Benefits",
              "companyName": "Contoso",
              "expirationDate": "2016-08-03T11:00:00.000Z",
              "topPicks": [
                "Employees only",
                "Add spouse or guest",
                "Add family"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Respuesta 5

Aquí está la respuesta del quinto ejemplo que contiene la nueva conversación y un identificador del hilo. Este nuevo hilo contiene una publicación creada automáticamente, que a su vez contiene la nueva extensión.

Nota: el objeto de respuesta que se muestra aquí puede haberse acortado para mejorar la legibilidad.

Para obtener la nueva extensión, primero debe obtener todas las publicaciones de este hilo, inicialmente debería haber solo una. A continuación, aplique el identificador de la publicación y el nombre de la extensión Com.Contoso.Benefits para obtener la extensión.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/conversations/$entity",
    "id": "AAQkADJToRlbJ5Mg7TFM7H-j3Y=",
    "threads": [
        {
            "id": "AAQkADJDtMUzsf_PdhAAswJOhGVsnkyDtMUzsf_Pdg=="
        }
    ]
}