Справочник по API REST Контактов Outlook (бета)

Область применения: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Примечание

Эта документация охватывает бета-версию API контактов в предварительной версии. Параметры предварительного просмотра могут быть изменены до завершения и могут нарушать код, который их использует. Поэтому в своем производственном коде вы должны использовать только производственную версию API. Если она доступна, предпочтительной версией в настоящее время является v2.0.

API контактов Outlook предоставляет доступ к контактам и папкам контактов, защищенным Azure Active Directory в Office 365, и к подобным данным в учетных записях Microsoft, конкретно в этих доменах: Hotmail.com, Live.com, MSN.com, Outlook.com, и Passport.com.

Примечание

Для упрощения этой справки в остальной части этой статьи при упоминании Outlook.com также подразумеваются и эти домены учетной записи Майкрософт.

Не интересуетесь бета-версией API? В оглавлении слева, перейдите к разделу Справка по API REST Office 365 и выберите нужную версию.

Все операции API Контактов

Операции с Контактами

Контакты хранятся в папках контактов. Вы можете получать, создавать, изменять и удалять контакты.

• Получить контакты
• Синхронизировать контакты и папки контактов
• Создать контакты
• Обновить контакты
• Удалить контакты

Операции с папками контактов

Папки контактов могут содержать контакты и другие папки контактов. Вы можете получить папки контактов и создать контакты в папке контактов.

• Получить папки контактов

Операции с фотографиями контактов

Каждый контакт может иметь дополнительное изображение контакта. Вы можете получить или установить фотографию для контакта.

• Получить фотографию контакта
• Установить фотографию контакта

См. также

• Ресурс API REST Контактов
• Ресурс папки API REST Контактов

Использование API REST Контактов

Проверка подлинности

Как и для других API REST Outlook, для каждого запроса к API Outlook необходимо включать допустимый маркер доступа. Получение маркера доступа требует, чтобы вы зарегистрировались и идентифицировали свою программу и получили соответствующее разрешение.

Вы можетеузнать больше о некоторых упрощенных параметрах регистрации и авторизации. Помните об этом, когда выполняете конкретные действия в API календаря.

Версия API

API REST календаря поддерживается во всех версиях API REST Outlook. Функциональность зависит от конкретной версии.

Целевой пользователь

Запросы API календаря всегда выполняются от имени текущего пользователя.

Дополнительные сведения, общие для всех подразделов API REST Outlook, см. в разделе Использование API REST Outlook.

Получение контактов

Вы можете получить коллекцию контактов или индивидуальный контакт из папки контактов.

Минимальная требуемая область

Одно из следующих:

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

• wl.basic

• Получить коллекцию контактов

• Получить контакт

Получить коллекцию контактов

Получите все контакты в почтовом ящике подписанного пользователя(.../me/contacts) или из указанной папки контактов.

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

Обязательный параметр	Тип	Описание
Параметры URL-адреса
contact_folder_id	string	Идентификатор папки контактов, если вы получаете контакты из определенной папки.

Примечание

По умолчанию каждый контакт в ответе включает все его свойства. Используйте $select, чтобы указать только те свойства, которые вам нужны для лучшей производительности. Свойство Id всегда возвращается. Параметры фильтрации, сортировки и разбиения на страницы см. в статье Параметры запроса OData.

Пример запроса

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

Пример отклика

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

Тип отклика

Запрошенная коллекция контактов.

Получить контакт

Минимальная требуемая область

Одно из следующих:

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

Получить контакт, используя идентификатор контакта.

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

Обязательный параметр	Тип	Описание
Параметры URL-адреса
contact_id	string	Идентификатор контакта.

Тип отклика

Запрошенный контакт.

Пример запроса

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

Пример отклика

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

Примечание

По умолчанию ответ включает все свойства контакта. Используйте $select, чтобы указать только те свойства, которые вам нужны для лучшей производительности. Свойство Id всегда возвращается. Параметры фильтрации, сортировки и разбиения на страницы см. в статье Параметры запроса OData.

В следующем примере показано, как использовать $select для указания возврата в ответе только свойств EmailAddresses, GivenName и Surname контакта.

Пример запроса

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

Пример отклика

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

Синхронизировать контакты и папки контактов

Вы можете синхронизировать свой локальный список контактов с контактами на сервере. Синхронизация контактов - операция для отдельной папки. Например, вы можете синхронизировать все контакты в папке с корневыми контактами. Если у вас есть дополнительные папки контактов, вам придется синхронизировать каждую папку по отдельности.

Синхронизация поддерживает только полную синхронизацию. С каждым запросом возвращаются все контакты в указанной папке.

Синхронизация папки контактов обычно требует двух или более запросов GET. Вы делаете запрос GET так же, как и вы получаете контакты, за исключением того, что вы добавляете следующие заголовки запросов.

• Вы должны указать заголовок Prefer: odata.track-changes во всех ваших запросах синхронизации.

• Вы можете указать заголовок Prefer: odata.maxpages = {n}, чтобы установить максимальное количество контактов, возвращаемых в каждом запросе.

  Второй и последующие запросы GET отличаются от первого запроса GET, включая либо deltaToken или skipToken полученных в предыдущем ответе.

  Первоначальный ответ на запрос синхронизации всегда возвращает deltaToken. Вы всегда должны сделать второй запрос GET, используя deltaToken для определения наличия каких-либо дополнительных контактов. Второй запрос будет возвращать дополнительные контакты и либо skipToken, если доступно больше контактов, или deltaToken, если последний контакт был отправлен.

Минимальная требуемая область

Одно из следующих:

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

Обязательный параметр	Тип	Описание
Параметры заголовка
Prefer	odata.track-changes	Указывает, что запрос является запросом синхронизации.
Prefer	odata.maxpagesize	Устанавливает количество контактов, возвращаемых в каждом ответе.
Параметр URL-адреса
folderName	string	Имя папки для синхронизации.
odata.deltaLink	String	Маркер, который указывает последний раз, когда была синхронизирована папка.
odata.skiptoken	String	Маркер, который указывает, что есть еще сообщения для загрузки.

Тип отклика

Коллекция, содержащая запрошенные контакты и deltaToken, которые вы используете для запроса дополнительных страниц контактных данных с сервера и для запроса инкрементной синхронизации. Если число возвращаемых контактов больше, чем значение, указанное в заголовке odata.maxpagesize, ответ будет возвращен на нескольких страницах.

Ответ будет включать заголовок Preference-Applied: odata-trackchanges. Если вы попытаетесь синхронизировать ресурс, который не поддерживается, этот заголовок не будет возвращен в ответе. Чтобы избежать ошибок, проверьте этот заголовок перед обработкой отклика.

Примечание

По умолчанию отклик включает все свойства указанных контактов. Используйте $select, чтобы указать только те свойства, которые вам нужны для максимальной производительности. Свойство Id всегда возвращается. Не используйте $filter, $ orderby, $search или $top, поскольку они не поддерживаются для синхронизации контактов или папок контакта. Подробнее см.статью Параметры запроса OData.

Примеры

Первоначальный запрос полной синхронизации:

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

Включите следующие заголовки:

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

Второй запрос на сервер после запроса полной синхронизации:

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

Включите следующие заголовки:

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

Второй ответ с сервера с дополнительными доступными страницами:

Заголовок

Preference-Applied: odata.track-changes

Текст

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

Сообщения полезной нагрузки

Второй или последующий отклик от сервера, когда все контакты были отправлены:

Заголовок

Preference-Applied: odata.track-changes

Текст

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

Сообщения полезной нагрузки

Запрос на сервер при наличии дополнительных страниц:

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

Включите следующие заголовки:

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

Создать контакты

Создайте контакт в указанной папке «Контакты».

Создание контакта

Создание контакта

Минимальная требуемая область

Одно из следующих:

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

Добавление контакта в корневую папку с контактами или конечную точку contacts другой папки с контактами.

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

Обязательный параметр	Тип	Описание
Параметры URL-адреса
contact_folder_id	string	Идентификатор папки контактов, если вы создаете контакт в определенной папке контакта.
Параметры текста сообщения
GivenName	string	Собственное имя контакта.

Укажите параметр GivenName и любое доступное для записи свойство ресурса contact в теле запроса.

Пример запроса

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

Пример отклика

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

Тип отклика

Новый объект contact.

Обновить контакты

Измените свойства контакта.

• Обновить контакт

Обновить контакт

Минимальная требуемая область

Одно из следующих:

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

Укажите любое доступное для записи свойствоконтакта в теле запроса. Изменены только те свойства, которые вы указали.

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

Обязательный параметр	Тип	Описание
Параметры URL-адреса
contact_id	string	Идентификатор контакта.

Пример запроса

Следующий пример задает почтовый адрес контакта и устанавливает флаг напоминания о сроках исполнения.

Примечание

Когда для параметра Flag.FlagStatus установлено значение Flagged, параметр 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"
        }
    }
}

Пример отклика

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

Пример запроса

В следующем примере устанавливается ранее отмеченный контакт для 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"
  }
}

Пример отклика

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

Тип отклика

Обновленный объект contact.

Удалить контакты

Удаление контакта. Удаленное содержимое не может быть восстановлено.

Подробнее см. Удаление элементов с помощью EWS в Exchange.

• Удалить контакт

Удаление контакта

Минимальная требуемая область

Одно из следующих:

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

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

Обязательный параметр	Тип	Описание
Параметры URL-адреса
contact_id	string	Идентификатор контакта.

Пример запроса

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

Пример отклика

Status code: 204

Получить папки контактов

Вы можете получить коллекцию папок контактов или папку контактов.

• Получить коллекцию папок контактов
• Получить папку контактов

Получить коллекцию папок контактов

Минимальная требуемая область

Одно из следующих:

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

Получите все папки контактов в почтовом ящике вошедшего пользователя (.../me/contactfolders) или в указанной папке контакта.

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

Примечание

Параметры фильтрации, сортировки и разбиения на страницы см. в статье Параметры запроса OData.

Обязательный параметр	Тип	Описание
Параметры URL-адреса
contact_folder_id	string	Идентификатор папки контактов, если вы получаете папки контактов из определенной папки контактов.

Пример запроса

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

Пример отклика

Код состояния: 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"
        }
    ]
}

Тип отклика

Запрошенная коллекция папок контактов.

Получить папку контактов

Минимальная требуемая область

Одно из следующих:

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

Получение папки контактов с помощью ее идентификатора.

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

Примечание

Параметры фильтрации, сортировки и разбиения на страницы см. в статье Параметры запроса OData.

Обязательный параметр	Тип	Описание
Параметры URL-адреса
contact_folder_id	string	Идентификатор папки контактов.

Пример запроса

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

Пример отклика

Код состояния: 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
}

Тип отклика

Запрошенная папка контактов.

Получить фотографию и метаданные контакта

• Получить фотографию контакта
• Получить метаданные фотографии контакта

Получить фотографию контакта

Минимальная требуемая область

Одно из следующих:

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

Получите фотографию указанного контакта пользователя с подписью.

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

Обязательный параметр	Тип	Описание
Параметры URL-адреса
contact_id	string	Идентификатор, определяющий конкретный контакт вошедшего пользователя.

Пример запроса

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

Данные в ответе

Содержит двоичные данные запрошенной фотографии. Код HTTP-отклика: 200.

Операция возвращает HTTP 404, если контакт не имеет контактной фотографии в Exchange Online.

Получить метаданные фотографии контакта

Минимальная требуемая область

Одно из следующих:

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

Получите метаданные контактной фотографии, которая включает в себя тип содержимого, ширину и высоту в пикселях.

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

Обязательный параметр	Тип	Описание
Параметры URL-адреса
contact_id	string	Идентификатор, определяющий конкретный контакт вошедшего пользователя.

Пример запроса

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

Пример данных ответа

Успешный запрос возвращает 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
}

Установить фотографию контакта

Минимальная требуемая область

Одно из следующих:

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

Назначьте фотографию указанному пользователю, выполнившему вход в систему. Фотография должна быть в двоичном формате. Она заменяет любую существующую фотографию для этого контакта.

Используйте только PUT для этой операции в бета-версии.

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

Обязательный параметр	Тип	Описание
Параметры URL-адреса
contact_id	string	Идентификатор, определяющий конкретный контакт вошедшего пользователя.

Пример запроса

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

Включите двоичные данные фотографии в текст запроса.

Данные в ответе

Успешный запрос возвращает HTTP 200.

Дальнейшие действия

Независимо от того, готовы ли вы приступить к созданию приложения или хотите изучить больше материалов, у нас есть все необходимое.

• Начало работы с API REST Почты, Календаря и Контактов.
• Хотите увидеть примеры? Вот они.

Или узнайте больше об использовании платформы Office 365 здесь:

• API REST Outlook для центра разработок Outlook
• Обзор разработки на платформе Office 365
• Проверка подлинности приложений и авторизация ресурсов в Office 365
• Зарегистрируйте приложение в Azure AD вручную, чтобы оно могло получать доступ к API Office 365
• Справка по API Почты
• Справка по API календаря
• API REST Задание
• API OneDrive
• Справка по операциям API REST службы обнаружения
• Справочник ресурсов по API REST Почта, Календарь, Контакты и Задача