Criar uma propriedade estendida de valor único

Artigo
07/04/2024

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Cuidado

As tarefas do Outlook foram preteridas e deixaram de devolver dados a 10 de agosto de 2022. Atualize as aplicações existentes que utilizam esta funcionalidade com tarefas do Outlook.

Crie uma ou mais propriedades estendidas de vários valores em uma instância nova ou existente de um recurso.

Há suporte para as seguintes fontes de dados:

São suportados os seguintes recursos de grupo:

grupo calendar
grupo event
grupo post

Confira Visão geral de propriedades estendidas para saber mais sobre quando usar extensões abertas ou propriedades estendidas e sobre como especificar propriedades estendidas.

Esta API está disponível nas seguintes implementações de cloud nacionais.

Serviço global	US Government L4	US Government L5 (DOD)	China operada pela 21Vianet
✅	✅	✅	✅

Permissões

Consoante o recurso no qual está a criar a propriedade expandida e o tipo de permissão (delegado ou aplicação) que pedir, a permissão especificada na tabela seguinte é o mínimo necessário para chamar esta API. Para saber mais, incluindo como escolher permissões, confira Permissões.

Recurso com suporte	Delegada (conta corporativa ou de estudante)	Delegada (conta pessoal da Microsoft)	Application
calendar	Calendars.ReadWrite	Calendars.ReadWrite	Calendars.ReadWrite
contato	Contacts.ReadWrite	Contacts.ReadWrite	Contacts.ReadWrite
contactFolder	Contacts.ReadWrite	Contacts.ReadWrite	Contacts.ReadWrite
evento	Calendars.ReadWrite	Calendars.ReadWrite	Calendars.ReadWrite
grupo calendar	Group.ReadWrite.All	Sem suporte	Sem suporte
grupo event	Group.ReadWrite.All	Sem suporte	Sem suporte
grupo post	Group.ReadWrite.All	Sem suporte	Sem suporte
mailFolder	Mail.ReadWrite	Mail.ReadWrite	Mail.ReadWrite
mensagem	Mail.ReadWrite	Mail.ReadWrite	Mail.ReadWrite
Tarefa do Outlook	Tasks.ReadWrite	Tasks.ReadWrite	Incompatível
Pasta de tarefas do Outlook	Tasks.ReadWrite	Tasks.ReadWrite	Sem suporte

Solicitação HTTP

Você pode criar propriedades estendidas em uma instância de recurso nova ou existente.

Para criar uma ou mais propriedades estendidas em uma nova instância de recurso, use a mesma solicitação REST válida para a criação da instância e inclua as propriedades da nova instância de recurso e a propriedade estendida no corpo da solicitação. Alguns recursos suportam a criação de várias formas. Para obter mais informações sobre como criar estas instâncias de recursos, consulte os tópicos correspondentes para criar uma mensagem, mailFolder, evento, calendário, contacto, contactFolder, tarefa do Outlook, pasta de tarefas do Outlook, evento de grupo e publicação de grupo.

Veja a seguir a sintaxe das solicitações.

POST /me/messages
POST /users/{id|userPrincipalName}/messages
POST /me/mailFolders/{id}/messages

POST /me/mailFolders
POST /users/{id|userPrincipalName}/mailFolders

POST /me/events
POST /users/{id|userPrincipalName}/events

POST /me/calendars
POST /users/{id|userPrincipalName}/calendars

POST /me/contacts
POST /users/{id|userPrincipalName}/contacts

POST /me/contactFolders
POST /users/{id|userPrincipalName}/contactFolders

POST /me/outlook/tasks
POST /users/{id|userPrincipalName}/outlook/tasks
POST /me/outlook/taskFolders/{id}/tasks
POST /users/{id|userPrincipalName}/outlook/taskFolders/{id}/tasks
POST /me/outlook/taskGroups/{id}/taskFolders/{id}/tasks
POST /users/{id|userPrincipalName}/outlook/taskGroups/{id}/taskFolders/{id}/tasks

POST /me/outlook/taskFolders
POST /users/{id|userPrincipalName}/outlook/taskFolders
POST /me/outlook/taskGroups/{id}/taskFolders
POST /users/{id|userPrincipalName}/outlook/taskGroups/{id}/taskFolders

POST /groups/{id}/events

POST /groups/{id}/threads/{id}/posts/{id}/reply
POST /groups/{id}/conversations/{id}/threads/{id}/posts/{id}/reply
POST /groups/{id}/threads/{id}/reply
POST /groups/{id}/conversations/{id}/threads/{id}/reply
POST /groups/{id}/threads
POST /groups/{id}/conversations

Para criar uma ou mais propriedades estendidas em uma instância de recurso existente, especifique essa instância na solicitação e inclua a propriedade estendida no corpo da solicitação.

Nota Não pode criar uma propriedade expandida numa publicação de grupo existente.

PATCH /me/messages/{id}
PATCH /users/{id|userPrincipalName}/messages/{id}
PATCH /me/mailFolders/{id}/messages/{id}

PATCH /me/mailFolders/{id}
PATCH /users/{id|userPrincipalName}/mailFolders/{id}

PATCH /me/events/{id}
PATCH /users/{id|userPrincipalName}/events/{id}

PATCH /me/calendars/{id}
PATCH /users/{id|userPrincipalName}/calendars/{id}

PATCH /me/contacts/{id}
PATCH /users/{id|userPrincipalName}/contacts/{id}

PATCH /me/contactFolders/{id}
PATCH /users/{id|userPrincipalName}/contactFolders/{id}

PATCH /me/outlook/tasks/{id}
PATCH /users/{id|userPrincipalName}/outlook/tasks/{id}
PATCH /me/outlook/taskFolders/{id}/tasks/{id}
PATCH /users/{id|userPrincipalName}/outlook/taskFolders/{id}/tasks/{id}
PATCH /me/outlook/taskGroups/{id}/taskFolders/{id}/tasks/{id}
PATCH /users/{id|userPrincipalName}/outlook/taskGroups/{id}/taskFolders/{id}/tasks/{id}

PATCH /me/outlook/taskFolders/{id}
PATCH /users/{id|userPrincipalName}/outlook/taskFolders/{id}
PATCH /me/outlook/taskGroups/{id}/taskFolders/{id}
PATCH /users/{id|userPrincipalName}/outlook/taskGroups/{id}/taskFolders/{id}

PATCH /groups/{id}/events/{id}

Cabeçalhos de solicitação

Nome	Valor
Autorização	{token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type	application/json

Corpo da solicitação

Forneça um corpo JSON de cada objeto singleValueLegacyExtendedProperty na propriedade da coleção singleValueExtendedProperties da instância do recurso.

Propriedade	Tipo	Descrição
singleValueExtendedProperties	Coleção singleValueLegacyExtendedProperty	Uma matriz de uma ou mais propriedades estendidas de valor único.
id	String	Para cada propriedade na coleção singleValueExtendedProperties, especifique isso para identificar a propriedade. Deve seguir um dos formatos com suporte. Para saber mais, confira Visão geral das propriedades estendidas do Outlook. Obrigatório.
valor	string	Para cada propriedade na coleção singleValueExtendedProperties, especifique o valor da propriedade. Obrigatório.

Ao criar uma propriedade estendida em uma nova instância de recurso, além da nova coleção singleValueExtendedProperties, forneça uma representação JSON dessa instância de recurso (ou seja, message, mailFolder, event, etc.)

Resposta

Código da resposta

Uma operação bem-sucedida na criação de uma propriedade estendida em uma nova instância de recurso retorna 201 Created, exceto em uma nova postagem de grupo. Dependendo do método usado, a operação pode retornar 200 OK ou 202 Accepted.

Em uma instância de recurso existente, uma operação de criação bem-sucedida retorna 200 OK.

Corpo da resposta

Ao criar uma propriedade estendida, a resposta inclui apenas a instância nova ou existente, mas não a nova propriedade estendida. Para ver a propriedade estendida recém-criada, obtenha a instância expandida com a propriedade estendida.

Ao criar uma propriedade expandida numa novapublicação de grupo ao responder a um thread ou publicação, a resposta inclui apenas um código de resposta, mas não a nova publicação nem a propriedade expandida.

Exemplo

Solicitação 1

O primeiro exemplo cria um novo evento e uma propriedade de valor único estendida na mesma operação POST. Além das propriedades que você normalmente incluiria para um novo evento, o corpo da solicitação inclui a coleção singleValueExtendedProperties, que contém uma propriedade estendida de valor único e as seguintes informações sobre a propriedade:

id especifica o tipo de propriedade como String, o GUID e a propriedade nomeada Fun.
value especifica Food como o valor da propriedade Fun.

POST https://graph.microsoft.com/beta/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": [
     {
           "id":"String {66f5a359-4659-4830-9070-00040ec6ac6e} Name Fun",
           "value":"Food"
     }
  ]
}

Resposta 1

Uma resposta bem-sucedida é indicada por um código de resposta HTTP 201 Created e inclui o novo evento em seu corpo, semelhante à resposta da criação de apenas um evento. A resposta não inclui quaisquer propriedades expandidas recentemente criadas.

Para ver a propriedade estendida recém-criada, obtenha o evento expandido com a propriedade estendida.

Solicitação 2

O segundo exemplo cria uma propriedade estendido de valor único para a mensagem especificada existente. A propriedade estendida é o único elemento na matriz singleValueExtendedProperties. O corpo da solicitação inclui o seguinte para essa propriedade estendida:

id especifica o tipo de propriedade como String, o GUID e a propriedade nomeada Color.
value especifica Green como o valor da propriedade Color.

PATCH https://graph.microsoft.com/beta/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')

Content-Type: application/json

{
  "singleValueExtendedProperties": [
      {
         "id":"String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
         "value":"Green"
      }
    ]
}

Resposta 2

Uma resposta bem-sucedida é indicada por um código de resposta HTTP 200 OK e inclui a mensagem especificada em seu corpo, semelhante à resposta da atualização de uma mensagem. A resposta não inclui a propriedade expandida recentemente criada.

Para ver a propriedade estendida recém-criada, obtenha a mensagem expandida com a propriedade estendida.

Partilhar via