Referência da API REST de Contatos do Outlook (beta)

Aplica-se a: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Observação

Esta documentação cobre a versão beta da API de Contatos em versão prévia. Os recursos de versão prévia estão sujeitos a alterações antes da finalização e podem violar o código que os utiliza. Por essa razão, em geral, você deve usar somente uma versão de produção de uma API em seu código de produção. Se disponível, a v2.0 é atualmente a versão preferida.

A API de Contatos do Outlook fornece acesso protegido a contatos e pastas de contatos de um usuário pelo Active Directory do Azure no Office 365 e a dados semelhantes nas contas da Microsoft, especificamente nestes domínios: Hotmail.com, Live.com, MSN.com, Outlook.com, e Passport.com.

Observação

Para simplificar a referência, o restante deste artigo usa o Outlook.com para incluir esses domínios de conta da Microsoft.

Não tem interesse na versão beta da API? No sumário à esquerda, vá para a seção de Referência da API REST do Office 365 e selecione a versão desejada.

Todas as operações da API de Contatos

Operações de contato

Contatos são armazenados em pastas de contatos. Você pode obter, criar, alterar e excluir contatos.

• Obter contatos
• Sincronizar contatos e pastas de contatos
• Criar contatos
• Atualizar contatos
• Excluir contatos

Operações de pasta de contato

Pastas de contatos podem conter contatos e outras pastas de contatos. Você pode obter pastas de contatos e criar contatos em uma pasta de contatos.

• Obter pastas de contatos

Operações de foto do contato

Cada contato pode ter uma imagem de contato opcional. Você pode obter ou definir uma foto para um contato.

• Obter foto de contato
• Definir foto de contato

Confira também

• Recurso de contato da API REST
• Recursos de pasta de contato da API REST

Usar a API REST de Contatos

Autenticação

Assim como acontece com outras APIs REST do Outlook, para cada solicitação enviada à API de Contatos você deve incluir um token de acesso válido. A obtenção de um token de acesso exige que você tenha registrado e identificado seu aplicativo e obtido a autorização adequada.

Você pode aprender mais sobre algumas opções simplificadas de registro e autorização. Tenha isso em mente ao prosseguir com as operações específicas na API de Contatos.

Versão da API

A API REST de Contatos é suportada em todas as versões da API REST do Outlook. A funcionalidade pode variar dependendo da versão específica.

Usuário destino

As solicitações da API de Contatos são sempre feitas em nome do usuário atual.

Veja Usar a API REST do Outlook para obter mais informações comuns a todos os subconjuntos da API REST do Outlook.

Obter contatos

Você pode obter uma coleção de contatos ou um único contato de uma pasta de contatos.

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.read

• wl.basic

• Obter uma coleção de contatos

• Obter um contato

Obter uma coleção de contatos

Obter todos os contatos na caixa de correio do usuário conectado (.../me/contacts) ou da pasta de contatos especificada.

GET https://outlook.office.com/api/beta/me/contacts
GET https://outlook.office.com/api/beta/me/contactfolders/{contact_folder_id}/contacts

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_folder_id	cadeia de caracteres	A ID da pasta de contatos, se estiver obtendo contatos de uma pasta específica.

Observação

Por padrão, cada contato na resposta inclui todas as suas propriedades. Use $select para especificar somente as propriedades necessárias para um melhor desempenho. A propriedade Id é sempre retornada. Confira Parâmetros de consulta do OData para ver parâmetros de filtragem, classificação e paginação.

Exemplo de solicitação

GET https://outlook.office.com/api/beta/me/contacts?$select=EmailAddresses,GivenName,Surname

Exemplo de resposta

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Contacts(EmailAddresses,GivenName,Surname)",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk3AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa7\"",
            "Id": "AAMkAGI2THk3AAA=",
            "GivenName": "Rob",
            "Surname": "Young",
            "EmailAddresses": [
                {
                    "Name": "roby@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "roby@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THkzAAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa3\"",
            "Id": "AAMkAGI2THkzAAA=",
            "GivenName": "Janet",
            "Surname": "Schorr",
            "EmailAddresses": [
                {
                    "Name": "janets@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "janets@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        }
    ]
}

Tipo de resposta

A coleção de contatos solicitada.

Obter um contato

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.read
• wl.basic

Obtenha um contato usando a ID do contato.

GET https://outlook.office.com/api/beta/me/contacts/{contact_id}

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_id	cadeia de caracteres	A ID do contato.

Tipo de resposta

O contato solicitado.

Exemplo de solicitação

GET https://outlook.office.com/api/beta/me/contacts/AAMkADlkAAAMRFUEAAA=

Exemplo de resposta

Status code: 200

{
    "@odata.context":"https://outlook.office365.com/api/beta/$metadata#Me/Contacts/$entity",
    "@odata.id":"https://outlook.office365.com/api/beta/Users('af183ae6-7efa-41e4-aa87-fe8790598625@9ac5b33f-49cf-45f7-9ef1-b581dce364d8')/Contacts('AAMkADlkAAAMRFUEAAA=')",
    "@odata.etag":"W/\"EQAAABYAAADDii8zlkFETIcBiRn8yAbgAAAMRdhl\"",
    "Id":"AAMkADlkAAAMRFUEAAA=",
    "CreatedDateTime":"2016-07-16T06:43:15Z",
    "LastModifiedDateTime":"2016-07-16T06:43:15Z",
    "ChangeKey":"EQAAABYAAADDii8zlkFETIcBiRn8yAbgAAAMRdhl",
    "Categories":[
    ],
    "ParentFolderId":"AAMkADlk8yAbgAAAAAAEkAAA=",
    "Birthday":null,
    "FileAs":"",
    "DisplayName":"Garret Vargas",
    "GivenName":"Garret",
    "Initials":null,
    "MiddleName":null,
    "NickName":null,
    "Surname":"Vargas",
    "Title":null,
    "YomiGivenName":null,
    "YomiSurname":null,
    "YomiCompanyName":null,
    "Generation":null,
    "EmailAddresses":[
        {
            "Name":"Garret Vargas",
            "Address":"GarretV@contoso.onmicrosoft.com"
        }
    ],
    "Websites":[
    ],
    "ImAddresses":[
        "sip:garretv@contoso.onmicrosoft.com"
    ],
    "JobTitle":"CVP Operations",
    "CompanyName":"",
    "Department":"Operations",
    "OfficeLocation":"36/2121",
    "Profession":null,
    "AssistantName":null,
    "Manager":null,
    "Phones":[
        {
            "Type":"Home",
            "Number":""
        },
        {
            "Type":"Business",
            "Number":"+1 206 555 0105"
        },
        {
            "Type":"Mobile",
            "Number":""
        }
    ],
    "PostalAddresses":[
        {
            "Type":"Business",
            "City":"Seattle"
        }
    ],
    "SpouseName":null,
    "PersonalNotes":null,
    "Children":[
    ],
    "Gender":null,
    "IsFavorite":null,
    "Flag":{
        "FlagStatus":"NotFlagged"
    }
}

Observação

Por padrão, a resposta inclui todas as propriedades do contato. Use $select para especificar somente as propriedades necessárias para um melhor desempenho. A propriedade Id é sempre retornada. Confira Parâmetros de consulta do OData para ver parâmetros de filtragem, classificação e paginação.

O exemplo a seguir mostra como usar $select para especificar que apenas as propriedades EmailAddresses, GivenName, e Surname do contato sejam retornadas na resposta.

Exemplo de solicitação

GET https://outlook.office.com/api/beta/me/contacts/AAMkAGI2THk0AAA=?$select=EmailAddresses,GivenName,Surname

Exemplo de resposta

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Contacts(EmailAddresses,GivenName,Surname)/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('af183ae6-7efa-41e4-aa87-fe8790598625@9ac5b33f-49cf-45f7-9ef1-b581dce364d8')/Contacts('AAMkADlkAAAMRFUEAAA=')",
    "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4\"",
    "Id": "AAMkADlkAAAMRFUEAAA=",
    "GivenName": "Garth",
    "Surname": "Vargas",
    "EmailAddresses": [
       {
            "Name":"Garret Vargas",
            "Address":"GarretV@contoso.onmicrosoft.com"
        }
    ]
}

Sincronizar contatos e pastas de contatos

Você pode sincronizar sua lista local de contatos com os contatos no servidor. A sincronização de contatos é uma operação feita por pasta, por exemplo, você pode sincronizar todos os contatos em sua pasta de Contatos raiz. Se você tiver outras pastas de Contatos, precisará sincronizar cada uma delas individualmente.

A sincronização suporta apenas a sincronização completa. Todos os contatos na pasta especificada são retornados com cada solicitação.

Sincronizar uma pasta de contatos normalmente requer duas ou mais solicitações GET. A solicitação GET é feita de maneira muito parecida com a que você obtém contatos, a diferença é que você adiciona os seguintes cabeçalhos de solicitação.

• Você deve especificar o cabeçalho Prefer: odata.track-changes em todas as suas solicitações de sincronização.

• Você pode especificar o cabeçalho Prefer: odata.maxpages = {n} para definir o número máximo de contatos retornados em cada solicitação.

  A segunda e as subsequentes solicitações GET diferem da primeira, pois incluem um deltaToken ou um skipToken recebido em uma resposta anterior.

  A resposta inicial a uma solicitação de sincronização sempre retorna um deltaToken. Você deve sempre fazer uma segunda solicitação GET usando o deltaToken para determinar se há contatos adicionais. A segunda solicitação retornará contatos adicionais e um skipToken se houver mais contatos disponíveis, ou um deltaToken se o último contato foi enviado.

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.read
• wl.basic

GET https://outlook.office.com/api/beta/me/Contacts
GET https://outlook.office.com/api/beta/me/ContactFolders/{folderName}

Parâmetro obrigatório	Tipo	Descrição
Parâmetros do cabeçalho
Preferir	odata.track-changes	Indica que a solicitação é uma solicitação de sincronização.
Preferir	odata.maxpagesize	Define o número de contatos retornados em cada resposta.
Parâmetro de URL
folderName	cadeia de caracteres	O nome da pasta a ser sincronizada.
odata.deltaLink	Cadeia de caracteres	O token que indica a última vez que a pasta foi sincronizada.
odata.skiptoken	Cadeia de caracteres	O token que indica que há mais mensagens para download.

Tipo de resposta

Uma coleção contendo os contatos solicitados e um deltaToken que você usa para solicitar páginas adicionais de dados de contatos do servidor e uma sincronização incremental. Se o número de contatos retornados for maior que o valor especificado no cabeçalho odata.maxpagesize a resposta será retornada em várias páginas.

A resposta incluirá um cabeçalho Preference-Applied: odata-trackchanges. Se você tentar sincronizar um recurso que não é suportado, esse cabeçalho não será retornado na resposta. Verifique esse cabeçalho antes de processar a resposta para evitar erros.

Observação

Por padrão, a resposta inclui todas as propriedades dos contatos especificados. Use $select para especificar apenas as propriedades que você precisa para um melhor desempenho. A propriedade Id é sempre retornada. Não use $filter, $orderby, $search ou $top, pois não são suportados para sincronizar contatos ou pastas de contatos. Consulte Parâmetros de consulta OData para mais detalhes.

Exemplos

Solicitação inicial para uma sincronização completa:

GET https://outlook.office.com/api/beta/Me/Contacts

Inclua os seguintes cabeçalhos:

• Prefer: odata.track-changes
• Prefer: odata.maxpagesize=100

Segunda solicitação para o servidor após uma solicitação de sincronização completa:

https://outlook.office.com/api/beta/Me/Contacts/?%24deltatoken=169ca50467d34d9fb8adb664961b9836

Inclua os seguintes cabeçalhos:

• Prefer: odata.track-changes
• Prefer: odata.maxpagesize=100

Segunda resposta do servidor com páginas adicionais disponíveis:

Cabeçalho

Preference-Applied: odata.track-changes

Corpo

@odata.deltaLink=https://outlook.office.com/api/beta/me/Contacts/messages/?%24skiptoken=169ca50467d34d9fb8adb664961b9836

Mensagens de conteúdo

Segunda ou subsequente resposta do servidor quando todos os contatos foram enviados:

Cabeçalho

Preference-Applied: odata.track-changes

Corpo

@odata.deltaLink=https://outlook.office.com/api/beta/me/Contacts/?%24deltatoken=169ca50467d34d9fb8adb664961b9836

Mensagens de conteúdo

Solicitação para o servidor quando páginas adicionais estiverem disponíveis:

https://outlook.office.com/api/beta/Me/Contacts/?%24skiptoken=169ca50467d34d9fb8adb664961b9836

Inclua os seguintes cabeçalhos:

• Prefer: odata.track-changes
• Prefer: odata.maxpagesize=100

Criar contatos

Crie um contato na pasta de Contatos especificada.

Criar um contato

Criar um contato

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.readwrite
• wl.contacts_create

Adicione um contato na pasta de contatos raiz ou no ponto de extremidade de contacts de outra pasta de contatos.

POST https://outlook.office.com/api/beta/me/contacts
POST https://outlook.office.com/api/beta/me/contactfolders/{contact_folder_id}/contacts

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_folder_id	cadeia de caracteres	ID da pasta de contatos, se você estiver criando um contato em uma pasta de contatos específica.
Parâmetros de corpo
GivenName	cadeia de caracteres	O nome dado ao contato.

Especifique o parâmetro GivenName e quaisquer propriedades graváveis de contato no corpo da solicitação.

Exemplo de solicitação

POST https://outlook.office.com/api/beta/me/contacts
Content-Type: application/json

{
  "GivenName": "Pavel",
  "Surname": "Bansky",
  "EmailAddresses": [
    {
      "Address": "pavelb@contoso.onmicrosoft.com",
      "Name": "Pavel Bansky"
    }
  ],
  "Phones": [
    {
      "Type": "Business",
      "Number": "+1 732 555 0102"
    }
  ]
}

Exemplo de resposta

Status code: 201

{
  "@odata.context":"https://outlook.office365.com/api/beta/$metadata#Me/Contacts/$entity",
  "@odata.id":"https://outlook.office365.com/api/beta/Users('af183ae6-7efa-41e4-aa87-fe8790598625@9ac5b33f-49cf-45f7-9ef1-b581dce364d8')/Contacts('AAMkADlkAAARKMK7AAA=')",
  "@odata.etag":"W/\"EQAAABYAAADDii8zlkFETIcBiRn8yAbgAAARKpia\"",
  "Id":"AAMkADlkAAARKMK7AAA=",
  "CreatedDateTime":"2016-07-20T23:59:37Z",
  "LastModifiedDateTime":"2016-07-20T23:59:38Z",
  "ChangeKey":"EQAAABYAAADDii8zlkFETIcBiRn8yAbgAAARKpia",
  "Categories":[
  ],
  "ParentFolderId":"AAMkADlk8yAbgAAAAAAEOAAA=",
  "Birthday":null,
  "FileAs":"",
  "DisplayName":"Pavel Bansky",
  "GivenName":"Pavel",
  "Initials":null,
  "MiddleName":null,
  "NickName":null,
  "Surname":"Bansky",
  "Title":null,
  "YomiGivenName":null,
  "YomiSurname":null,
  "YomiCompanyName":null,
  "Generation":null,
  "EmailAddresses":[
    {
      "Name":"Pavel Bansky",
      "Address":"pavelb@contoso.onmicrosoft.com"
    }
  ],
  "Websites":[
  ],
  "ImAddresses":[
  ],
  "JobTitle":null,
  "CompanyName":null,
  "Department":null,
  "OfficeLocation":null,
  "Profession":null,
  "AssistantName":null,
  "Manager":null,
  "Phones":[
    {
      "Type":"Business",
      "Number":"+1 732 555 0102"
    }
  ],
  "PostalAddresses":[
  ],
  "SpouseName":null,
  "PersonalNotes":null,
  "Children":[
  ],
  "Gender":null,
  "IsFavorite":null,
  "Flag":{
    "FlagStatus":"NotFlagged"
  }
}

Tipo de resposta

O novo contato.

Atualizar contatos

Alterar as propriedades de um contato.

• Atualizar um contato

Atualizar um contato

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.readwrite
• wl.contacts_create

Especifique quaisquer propriedades graváveis de contato no corpo da solicitação. Apenas as propriedades especificadas são alteradas.

PATCH https://outlook.office.com/api/beta/me/contacts/{contact_id}

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_id	cadeia de caracteres	A ID do contato.

Exemplo de solicitação

O exemplo a seguir define o endereço postal do contato e um sinalizador de acompanhamento.

Observação

Observação: Quando o sinalizador Flag.FlagStatus está definido como Flagged, não é possível defini-lo como Flag.CompletedDate.

PATCH https://outlook.office.com/api/beta/me/contacts/AAMkADlkAAARKMK7AAA=
Content-Type: application/json

{
  "PostalAddresses": [
    {
      "Type": "Business",
      "Street": "Some street",
      "City": "Seattle",
      "State": "WA",
      "PostalCode": "98121"
    }
  ],
  "Birthday": "1974-07-22",
  "Flag": {
    "FlagStatus": "Flagged",
       "DueDateTime": {
            "DateTime": "2017-12-22T08:00:00.0000000",
            "TimeZone": "UTC"
        },
        "StartDateTime": {
            "DateTime": "2017-12-18T08:00:00.0000000",
            "TimeZone": "UTC"
        }
    }
}

Exemplo de resposta

Status code: 200

{
  "@odata.context":"https://outlook.office365.com/api/beta/$metadata#Me/Contacts/$entity",
  "@odata.id":"https://outlook.office365.com/api/beta/Users('af183ae6-7efa-41e4-aa87-fe8790598625@9ac5b33f-49cf-45f7-9ef1-b581dce364d8')/Contacts('AAMkADlkAAARKMK7AAA=')",
  "@odata.etag":"W/\"EQAAABYAAADDii8zlkFETIcBiRn8yAbgAAARKpia\"",
  "Id":"AAMkADlkAAARKMK7AAA=",
  "CreatedDateTime":"2016-07-20T23:59:37Z",
  "LastModifiedDateTime":"2016-07-20T23:59:38Z",
  "ChangeKey":"EQAAABYAAADDii8zlkFETIcBiRn8yAbgAAARKpia",
  "Categories":[
  ],
  "ParentFolderId":"AAMkADlk8yAbgAAAAAAEOAAA=",
  "Birthday":"1974-07-22T00:00:00Z",
  "FileAs":"",
  "DisplayName":"Pavel Bansky",
  "GivenName":"Pavel",
  "Initials":null,
  "MiddleName":null,
  "NickName":null,
  "Surname":"Bansky",
  "Title":null,
  "YomiGivenName":null,
  "YomiSurname":null,
  "YomiCompanyName":null,
  "Generation":null,
  "EmailAddresses":[
    {
      "Name":"Pavel Bansky",
      "Address":"pavelb@contoso.onmicrosoft.com"
    }
  ],
  "Websites":[
  ],
  "ImAddresses":[
  ],
  "JobTitle":null,
  "CompanyName":null,
  "Department":null,
  "OfficeLocation":null,
  "Profession":null,
  "AssistantName":null,
  "Manager":null,
  "Phones":[
    {
      "Type":"Business",
      "Number":"+1 732 555 0102"
    }
  ],
  "PostalAddresses":[
    {
      "Type": "Business",
      "Street": "Some street",
      "City": "Seattle",
      "State": "WA",
      "PostalCode": "98121"
    }
  ],
  "SpouseName":null,
  "PersonalNotes":null,
  "Children":[
  ],
  "Gender":null,
  "IsFavorite":null,
  "Flag": {
        "FlagStatus": "Flagged",
        "DueDateTime": {
            "DateTime": "2017-12-22T08:00:00.0000000",
            "TimeZone": "UTC"
        },
        "StartDateTime": {
            "DateTime": "2017-12-18T08:00:00.0000000",
            "TimeZone": "UTC"
        }
  }
}

Exemplo de solicitação

O exemplo a seguir define um contato sinalizado anteriormente como Complete.

PATCH https://outlook.office.com/api/beta/me/contacts/AAMkADlkAAARKMK7AAA=
Content-Type: application/json

{
  "Flag": {
    "CompletedDateTime":{
      "DateTime": "2018-02-05T18:00:00",
      "TimeZone": "Pacific Standard Time"
    },
    "FlagStatus": "Complete"
  }
}

Exemplo de resposta

Status code: 200

{
  "@odata.context":"https://outlook.office365.com/api/beta/$metadata#Me/Contacts/$entity",
  "@odata.id":"https://outlook.office365.com/api/beta/Users('af183ae6-7efa-41e4-aa87-fe8790598625@9ac5b33f-49cf-45f7-9ef1-b581dce364d8')/Contacts('AAMkADlkAAARKMK7AAA=')",
  "@odata.etag":"W/\"EQAAABYAAADDii8zlkFETIcBiRn8yAbgAAARKpia\"",
  "Id":"AAMkADlkAAARKMK7AAA=",
  "CreatedDateTime":"2016-07-20T23:59:37Z",
  "LastModifiedDateTime":"2016-07-20T23:59:38Z",
  "ChangeKey":"EQAAABYAAABmngqUDhbeSLkRkXbBznTvAAEw/xwn",
  "Categories":[
  ],
  "ParentFolderId":"AAMkADlk8yAbgAAAAAAEOAAA=",
  "Birthday":"1974-07-22T00:00:00Z",
  "FileAs":"",
  "DisplayName":"Pavel Bansky",
  "GivenName":"Pavel",
  "Initials":null,
  "MiddleName":null,
  "NickName":null,
  "Surname":"Bansky",
  "Title":null,
  "YomiGivenName":null,
  "YomiSurname":null,
  "YomiCompanyName":null,
  "Generation":null,
  "EmailAddresses":[
    {
      "Name":"Pavel Bansky",
      "Address":"pavelb@contoso.onmicrosoft.com"
    }
  ],
  "Websites":[
  ],
  "ImAddresses":[
  ],
  "JobTitle":null,
  "CompanyName":null,
  "Department":null,
  "OfficeLocation":null,
  "Profession":null,
  "AssistantName":null,
  "Manager":null,
  "Phones":[
    {
      "Type":"Business",
      "Number":"+1 732 555 0102"
    }
  ],
  "PostalAddresses":[
    {
      "Type": "Business",
      "Street": "Some street",
      "City": "Seattle",
      "State": "WA",
      "PostalCode": "98121"
    }
  ],
  "SpouseName":null,
  "PersonalNotes":null,
  "Children":[
  ],
  "Gender":null,
  "IsFavorite":null,
  "Flag": {
    "FlagStatus": "Complete",
    "CompletedDateTime": {
        "DateTime": "2018-02-06T00:00:00.0000000",
        "TimeZone": "UTC"
    }
  }
}

Tipo de resposta

O contato atualizado.

Excluir contatos

Excluir um contato. O conteúdo excluído pode não ser recuperável.

Para saber mais, consulte Excluindo itens usando o EWS no Exchange.

• Excluir um contato

Excluir um contato

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.readwrite
• wl.contacts_create

DELETE https://outlook.office.com/api/beta/me/contacts/{contact_id}

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_id	cadeia de caracteres	A ID do contato.

Exemplo de solicitação

DELETE https://outlook.office.com/api/beta/me/contacts/AAMkAGE0Myy2hAAA=

Exemplo de resposta

Status code: 204

Obter pastas de contatos

Você pode obter uma coleção de pastas de contatos ou uma única pasta de contatos.

• Obter uma coleção de pastas de contatos
• Obter uma pasta de contatos

Obter uma coleção de pastas de contatos

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.read
• wl.basic

Obter todas as pastas de contatos da caixa de correio do usuário conectado (.../me/contactfolders) ou da pasta de contatos especificada.

GET https://outlook.office.com/api/beta/me/contactfolders
GET https://outlook.office.com/api/beta/me/contactfolders/{contact_folder_id}/childfolders

Observação

Confira Parâmetros de consulta do OData para ver parâmetros de filtragem, classificação e paginação.

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_folder_id	cadeia de caracteres	ID da pasta de contatos, se você estiver obtendo pastas de contatos de uma pasta de contatos específica.

Exemplo de solicitação

GET https://outlook.office.com/api/beta/me/contactfolders

Exemplo de resposta

Código de status: 200

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/ContactFolders",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/ContactFolders('AAMkAGI2TKI5AAA=')",
            "Id": "AAMkAGI2TKI5AAA=",
            "ParentFolderId": "AAMkAGI2AAEOAAA=",
            "DisplayName": "Finance",
            "WellKnownName": null
        },
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/ContactFolders('AQMkADA1MTgAAAA==')",
            "Id": "AQMkADA1MTgAAAA==",
            "ParentFolderId": "AAMkAGI2AAEOAAA=",
            "DisplayName": "Contacts",
            "WellKnownName": "contacts"
        }
    ]
}

Tipo de resposta

A coleção de pastas de contatos solicitada.

Obter uma pasta de contatos

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.read
• wl.basic

Obtenha uma pasta de contatos usando a respectiva ID.

GET https://outlook.office.com/api/beta/me/contactfolders/{contact_folder_id}

Observação

Confira Parâmetros de consulta do OData para ver parâmetros de filtragem, classificação e paginação.

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_folder_id	cadeia de caracteres	ID da pasta de contatos.

Exemplo de solicitação

GET https://outlook.office.com/api/beta/me/contactfolders/AAMkAGI2TKI5AAA=

Exemplo de resposta

Código de status: 200

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/ContactFolders/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/ContactFolders('AAMkAGI2TKI5AAA=')",
    "Id": "AAMkAGI2TKI5AAA=",
    "ParentFolderId": "AAMkAGI2AAEOAAA=",
    "DisplayName": "Finance",
    "WellKnownName": null
}

Tipo de resposta

A pasta de contatos solicitada.

Obter foto e metadados do contato

• Obter foto de contato
• Obter metadados da foto de contato

Obter foto de contato

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.read
• wl.basic

Obtenha a foto de contato do usuário conectado especificado.

GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')/photo/$value

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_id	cadeia de caracteres	A ID que especifica o contato específico do usuário conectado.

Exemplo de solicitação

GET https://outlook.office.com/api/beta/me/contacts('AAMkAGE1M2IyNGNm===')/photo/$value
Content-Type: image/jpg

Dados de resposta

Contém os dados binários da foto solicitada. O código de resposta HTTP é 200.

A operação retornará HTTP 404 se o contato ainda não tiver uma foto de contato no Exchange Online.

Obter metadados da foto de contato

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.read
• wl.basic

Obtenha os metadados de uma foto de contato, que incluem o tipo de conteúdo, largura e altura em pixels.

GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')/photo

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_id	cadeia de caracteres	A ID que especifica o contato específico do usuário conectado.

Exemplo de solicitação

GET https://outlook.office.com/api/beta/me/contacts('AAMkAGE1M2IyNGNm')/photo

Dados de resposta da amostra

Uma solicitação bem-sucedida retorna HTTP 200.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Contacts('AAMkAGE1M2IyNGNm')/photo/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-b826-40d7-b48b-57002df800e5@1717622f-49d1-4d0c-9d74-709fad664b77')/contacts('AAMkAGE1M2IyNGNm')/photo",
    "@odata.readLink": "https://outlook.office.com/api/beta/Users('ddfcd489-b826-40d7-b48b-57002df800e5@1717622f-49d1-4d0c-9d74-709fad664b77')/contacts('AAMkAGE1M2IyNGNm')/photo",
    "@odata.mediaContentType": "image/jpeg",
    "Id": "103X77",
    "Width": 103,
    "Height": 77
}

Definir foto de contato

Escopo mínimo necessário

Uma das seguintes opções:

• https://outlook.office.com/contacts.readwrite
• wl.contacts_create

Atribua uma foto ao contato do usuário conectado especificado. A foto deve estar em binário. Ela substitui qualquer foto existente para esse contato.

Use apenas PUT para essa operação na versão beta.

PUT https://outlook.office.com/api/beta/me/contacts('{contact_id}')/photo/$value

Parâmetro obrigatório	Tipo	Descrição
Parâmetros de URL
contact_id	cadeia de caracteres	A ID que especifica o contato específico do usuário conectado.

Exemplo de solicitação

PUT https://outlook.office.com/api/beta/me/contacts('AAMkAGE1M2IyNGNm===')/photo/$value
Content-Type: image/jpeg

Inclua os dados binários da foto no corpo da solicitação.

Dados de resposta

Uma solicitação bem-sucedida retorna HTTP 200.

Próximas etapas

Se você estiver pronto para começar a criar um aplicativo ou apenas quiser aprender mais, temos tudo o que você precisa.

• Introdução às APIs REST de Email, Calendário e Contatos.
• Quer exemplos? Nós temos.

Se preferir, aprenda mais sobre como usar a plataforma do Office 365:

• API REST do Outlook no Centro de Desenvolvimento do Outlook
• Visão geral sobre desenvolvimento na plataforma do Office 365
• Autenticação de aplicativo do Office 365 e autorização de recursos
• Registrar manualmente seu aplicativo no AD do Azure para que ele possa acessar as APIs do Office 365
• Referência da API de Email
• Referência da API de Calendário
• API REST de Tarefa
• API do OneDrive
• Referência de operações da API REST do Serviço de Descoberta
• Referência de recurso para as APIs REST de Email, Calendário, Contatos e Tarefa