Comentários Editar

Criar extensão aberta

  • Artigo
  • 16 minutos para o fim da leitura

Namespace: microsoft.graph

Crie uma extensão aberta (objeto openTypeExtension) e adicione propriedades personalizadas em uma instância nova ou existente de um recurso. Você pode criar uma extensão aberta em uma instância de recurso e armazenar dados personalizados para tudo isso na mesma operação, exceto para recursos específicos. Consulte limitações conhecidas de extensões abertas para obter mais informações.

A tabela na seção Permissões lista os recursos que oferecem suporte a extensões abertas.

Observação: Se você estiver criando extensões abertas em recursos do Outlook, confira considerações específicas do Outlook no tipo de recurso openTypeExtension.

Permissões

Dependendo do recurso para o qual você está criando a extensão e o tipo de permissão (delegado ou aplicativo) solicitado, a permissão especificada na tabela a seguir é a menos privilegiada necessária para fazer chamadas a esta API. Para saber mais, incluindo tomar cuidado antes de escolher as permissões mais privilegiadas, pesquise as seguintes permissões em Permissões.

Recurso com suporte Delegada (conta corporativa ou de estudante) Delegada (conta pessoal da Microsoft) Application
device Directory.AccessAsUser.All Sem suporte Device.ReadWrite.All
evento Calendars.ReadWrite Calendars.ReadWrite Calendars.ReadWrite
grupo Group.ReadWrite.All Sem suporte Group.ReadWrite.All
evento de grupo Group.ReadWrite.All Sem suporte Sem suporte
postagem de grupo Group.ReadWrite.All Sem suporte Group.ReadWrite.All
mensagem Mail.ReadWrite Mail.ReadWrite Mail.ReadWrite
organization Organization.ReadWrite.All Incompatível Organization.ReadWrite.All
contato pessoal Contacts.ReadWrite Contacts.ReadWrite Contacts.ReadWrite
todoTask Tasks.ReadWrite Tasks.ReadWrite Tasks.ReadWrite.All
todoTaskList Tasks.ReadWrite Tasks.ReadWrite Tasks.ReadWrite.All
user User.ReadWrite User.ReadWrite User.ReadWrite.All

Solicitação HTTP

Crie uma extensão em uma nova instância de recurso

Use a mesma solicitação REST usada para criar a instância.

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

Observação: essa sintaxe apresenta algumas maneiras comuns de criar as instâncias de recursos com suporte. Todas as outras sintaxes POST que permitem criar essas instâncias de recurso oferecem suporte à criação de extensões abertas nos mesmos de maneira semelhante.

Confira a seção Solicitar corpo sobre a inclusão de propriedades da nova instância do recurso e a extensão no corpo da solicitação.

Crie uma extensão em uma instância de recurso existente

Identifique a instância do recurso na solicitação e faça um POST para a propriedade de navegação 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

Observação: Esta sintaxe mostra algumas maneiras comuns de identificar uma instância de recurso, a fim de criar uma extensão nele. Todas as outras sintaxes que permitem identificar essas instâncias de recursos suportam a criação de extensões abertas nelas de forma semelhante.

Confira a seção Solicitar corpo sobre como incluir a extensão no corpo da solicitação.

Parâmetros do caminho

Parâmetro Tipo Descrição
id string Um identificador exclusivo para um objeto na coleção correspondente. Obrigatório.

Cabeçalhos de solicitação

Nome Valor
Autorização {token} de portador. Obrigatório.
Content-Type application/json

Corpo da solicitação

Forneça um corpo JSON de uma openTypeExtension, com os seguintes pares de nome/valor obrigatórios e dados personalizados adicionais. Os dados na carga JSON podem ser tipos primitivos ou matrizes de tipos primitivos.

Name Valor
@odata.type microsoft.graph.openTypeExtension
extensionName %unique_string%

Ao criar uma extensão em uma nova instância de recursos, além de novos objetos openTypeExtension, fornecem uma representação JSON das propriedades relevantes para criar uma instância de recurso deste tipo.

Resposta

Código da resposta

Dependendo da operação, o código de resposta pode ser 201 Created ou 202 Accepted.

Quando você cria uma extensão usando a mesma operação que você usa para criar uma instância de recurso, a operação retorna o mesmo código de resposta retornado quando você usa a operação para criar a instância de recurso sem a extensão. Consulte os tópicos correspondentes para a criação da instância, conforme listado acima.

Corpo da resposta

Cenário Recurso Corpo da resposta
Criar uma extensão ao criar explicitamente uma nova instância de recurso contact, event, message Inclui a nova instância expandida com o objeto openTypeExtension.
Criando uma extensão ao criar implicitamente uma instância de recursos postagem A resposta inclui somente um código de resposta, mas não um corpo de resposta.
Criar uma extensão em uma instância de recurso existente Todos os recursos com suporte Inclui o objeto openTypeExtension.

Exemplo

Solicitação 1

O primeiro exemplo cria uma mensagem e uma extensão na mesma chamada. O corpo da solicitação inclui o seguinte:

  • As propriedades subject, body e toRecipients típicas de uma nova mensagem.

  • E para a extensão:

    • O tipo microsoft.graph.openTypeExtension.
    • O nome da extensão "Com.Contoso.Referral".
    • Dados adicionais a serem armazenados como três propriedades personalizadas no conteúdo JSON: companyName, expirationDate e 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
    }
  ]
}

Resposta 1

Veja a seguir a resposta para o primeiro exemplo. O corpo da resposta inclui propriedades da nova mensagem e o seguinte para a nova extensão:

  • A propriedade id com o nome totalmente qualificado de microsoft.graph.openTypeExtension.Com.Contoso.Referral.
  • A propriedade padrão extensionName especificada na solicitação.
  • Os dados personalizados especificados na solicitação, armazenados como 3 propriedades personalizadas.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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
    }
  ]
}

Solicitação 2

O segundo exemplo cria uma extensão na mensagem especificada. O corpo da solicitação inclui o seguinte para essa extensão:

  • O tipo microsoft.graph.openTypeExtension.
  • O nome da extensão "Com.Contoso.Referral".
  • Dados adicionais a serem armazenados como 3 propriedades personalizadas na carga JSON: companyName, dealValue e 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"
}

Resposta 2

Veja a seguir a resposta para o segundo exemplo. O corpo da solicitação inclui o seguinte para a nova extensão:

  • A propriedade padrão extensionName.
  • A propriedade id com o nome totalmente qualificado de microsoft.graph.openTypeExtension.Com.Contoso.Referral.
  • Os dados personalizados a serem armazenados.
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"
}

Solicitação 3

O terceiro exemplo cria uma extensão no evento de grupo especificado. O corpo da solicitação inclui o seguinte para essa extensão:

  • O tipo microsoft.graph.openTypeExtension.
  • O nome da extensão "Com.Contoso.Deal".
  • Dados adicionais a serem armazenados como 3 propriedades personalizadas na carga JSON: companyName, dealValue e 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"
}

Resposta 3

Veja a seguir a resposta da terceira solicitação de exemplo.

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

Solicitação 4

O quarto exemplo cria uma extensão em uma nova postagem de grupo, usando a mesma chamada de ação reply para uma postagem de grupo existente. A ação reply cria uma nova postagem e uma nova extensão inserida nessa postagem. O corpo da solicitação inclui uma propriedade post que, por sua vez, contém o corpo da nova postagem e os seguintes dados para a nova extensão:

  • O tipo microsoft.graph.openTypeExtension.
  • O nome da extensão "Com.Contoso.HR".
  • Dados adicionais a serem armazenados como 3 propriedades personalizadas na carga JSON: companyName, expirationDate e a matriz de cadeias de caracteres 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"
      ]
    }
  ]
  }
}

Resposta 4

Veja a seguir a resposta do quarto exemplo. Criar uma extensão com êxito em uma nova postagem de grupo resulta apenas no código de resposta HTTP 202.

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

Solicitação 5

O quinto exemplo cria uma extensão em uma nova postagem de grupo usando a mesma operação POST para criar uma conversa. A operação POST cria uma nova conversa, thread ou postagem e uma nova extensão inserida na postagem. O corpo da solicitação inclui as propriedades Topic e Threads e o objeto filho post para a nova conversa. O objeto post, por sua vez, contém o corpo da nova postagem e os seguintes dados para a extensão:

  • O tipo microsoft.graph.openTypeExtension.
  • O nome da extensão "Com.Contoso.HR".
  • Dados adicionais a serem armazenados como 3 propriedades personalizadas na carga JSON: companyName, expirationDate e a matriz de cadeias de caracteres 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"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Resposta 5

Veja a seguir a resposta do quinto exemplo, que contém a nova conversa e uma ID de thread. Esse novo thread contém uma postagem criada automaticamente que, por sua vez, contém a nova extensão.

Observação: O objeto de resposta exibido aqui pode ser encurtado para legibilidade.

Para obter a nova extensão, primeiro obtenha todas as postagens desse thread. Inicialmente, deve haver somente uma. Em seguida, aplique a ID da postagem e o nome da extensão Com.Contoso.Benefits para obter a extensão.

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=="
        }
    ]
}