Compartir a través de


Crear extensión abierta

Espacio de nombres: microsoft.graph

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

Permissions

En función del recurso que cree, la extensión y el tipo de permiso (delegado o aplicación) solicitados, el permiso especificado en la tabla siguiente es el mínimo privilegio 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 Tasks.ReadWrite.All
todoTaskList Tasks.ReadWrite Tasks.ReadWrite Tasks.ReadWrite.All
usuario User.ReadWrite User.ReadWrite User.ReadWrite.All

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/{id|userPrincipalName}/events
POST /users/{id|userPrincipalName}/messages
POST /groups/{id}/events
POST /groups/{id}/threads/{id}/posts/{id}/reply
POST /users/{id|userPrincipalName}/contacts
POST /users/{id|userPrincipalName}/todo/lists/{id}/tasks
POST /users/{id|userPrincipalName}/todo/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 /devices/{id}/extensions
POST /users/{id|userPrincipalName}/events/{id}/extensions
POST /groups/{id}/extensions
POST /groups/{id}/events/{id}/extensions
POST /groups/{id}/threads/{id}/posts/{id}/extensions
POST /users/{id|userPrincipalName}/messages/{id}/extensions
POST /organization/{id}/extensions
POST /users/{id|userPrincipalName}/contacts/{id}/extensions
POST /users/{id|userPrincipalName}/extensions
POST /users/{id|userPrincipalName}/todo/lists/{id}/tasks/{id}/extensions
POST /users/{id|userPrincipalName}/todo/lists/{id}/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.

Parámetros de ruta de acceso

Parameter Tipo Descripción
id string Un identificador único para un objeto en la colección correspondiente. Necesario.

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 otro dato personalizado. Los datos de la carga JSON pueden ser de tipo primitivo o matrices de tipo primitivo.

Nombre Valor
@odata.type Microsoft.Graph.OpenTypeExtension
extensionName %unique_string%

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 artículos correspondientes para crear la instancia, como se mencionó anteriormente.

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.

Ejemplos

Ejemplo 1: Creación de un mensaje y una extensión en la misma llamada

Solicitud

En el ejemplo siguiente se 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/v1.0/me/messages

{
  "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

En el ejemplo siguiente se muestra 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 almacenados como tres propiedades personalizadas.

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

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages/$entity",
  "@odata.id": "https://graph.microsoft.com/v1.0/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/v1.0/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
    }
  ]
}

Ejemplo 2: Creación de una extensión en el mensaje especificado

Solicitud

En el ejemplo siguiente se 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 tres propiedades personalizadas en la carga JSON: companyName, dealValue y expirationDate.
POST https://graph.microsoft.com/v1.0/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions

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

Respuesta

En el ejemplo siguiente se muestra 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/v1.0/$metadata#Me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "@odata.id": "https://graph.microsoft.com/v1.0/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"
}

Ejemplo 3: Creación de una extensión en el evento de grupo especificado

Solicitud

En el ejemplo siguiente se 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 tres propiedades personalizadas en la carga JSON: companyName, dealValue y expirationDate.
POST https://graph.microsoft.com/v1.0/groups/f5480dfd-7d77-4d0b-ba2e-3391953cc74a/events/AAMkADVl17IsAAA=/extensions

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

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$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"
}

Ejemplo 4: Creación de una extensión en una nueva publicación de grupo

Solicitud

En el ejemplo siguiente se crea una extensión en una nueva publicación de grupo, utilizando 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".
  • Datos adicionales que se almacenarán como tres propiedades personalizadas en la carga de JSON: companyName, expirationDatey la matriz de cadenas topPicks.
POST https://graph.microsoft.com/v1.0/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/threads/AAQkADJizZJpEWwqDHsEpV_KA==/posts/AAMkADJiUg96QZUkA-ICwMubAAC1heiSAAA=/reply

{
  "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

En el ejemplo siguiente se muestra la respuesta. 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

Ejemplo 5: Creación de una extensión en una nueva publicación de grupo mediante la operación POST

Solicitud 5

En el ejemplo siguiente se crea una extensión en una nueva publicación de grupo con la misma operación POST 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".
  • Datos adicionales que se almacenarán como tres propiedades personalizadas en la carga de JSON: companyName, expirationDatey la matriz de cadenas topPicks.
POST https://graph.microsoft.com/v1.0/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/conversations

{
  "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

En el ejemplo siguiente se muestra la respuesta, que contiene la nueva conversación y un identificador de subproceso. 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/v1.0/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/conversations/$entity",
    "id": "AAQkADJToRlbJ5Mg7TFM7H-j3Y=",
    "threads": [
        {
            "id": "AAQkADJDtMUzsf_PdhAAswJOhGVsnkyDtMUzsf_Pdg=="
        }
    ]
}