Outlook の連絡先 REST API リファレンス (ベータ版)

[アーティクル]
06/30/2018

注意

このドキュメントは、プレビュー版に含まれる連絡先 API のベータ版について説明します。プレビュー機能は、最終版までに変更される場合があり、それらの機能を使用するコードが動作しなくなる場合もあります。このため、一般に、運用コードでは運用バージョンの API のみを使用してください。入手可能な場合、現時点ではバージョン 2.0 が優先バージョンです。

Outlook 連絡先 API は、Office 365 の Azure Active Directory によって保護されているユーザーの連絡先と連絡先フォルダーへのアクセス、および Microsoft アカウントの類似したデータへのアクセスを提供します。具体的には、次のドメインです。Hotmail.com、Live.com、MSN.com、Outlook.com、および Passport.com。

注意

リファレンスをわかりやすくするため、この記事の残りの部分では Outlook.com をこれらの Microsoft アカウントのドメインを含めた語として使用しています。

ベータ版の API が不要な場合 左の目次で、Office 365 REST API リファレンス セクションに移動し、使用したいバージョンを選択します。

連絡先 API のすべての操作

連絡先の操作

連絡先は、連絡先フォルダーに格納されます。連絡先を取得、作成、変更、および削除することができます。

連絡先を取得する
連絡先と連絡先フォルダーを同期する
連絡先を作成する
連絡先を更新する
連絡先を削除する

連絡先フォルダーの操作

連絡先フォルダーには、連絡先およびその他の連絡先フォルダーを含めることができます。連絡先フォルダーを取得し、連絡先フォルダーに連絡先を作成できます。

連絡先フォルダーの取得

連絡先の写真の操作

それぞれの連絡先に、オプションで連絡先の写真を指定できます。連絡先の写真を取得また設定することができます。

連絡先の写真を取得する
連絡先の写真を設定する

連絡先 REST API の使用

認証

他の Outlook REST API と同様に、連絡先 API へのすべての要求に対して、有効なアクセストークンを含める必要があります。アクセストークンを取得するには、アプリを登録して識別し、適切な承認を取得する必要があります。

効率化された登録と承認のオプションに関する詳細情報を参照してください。連絡先 API で特定の操作を続行する際には、この点に留意してください。

API のバージョン

連絡先 REST API は、すべてのバージョンの Outlook REST API でサポートされています。機能は、特定のバージョンによって異なる場合があります。

対象ユーザー

連絡先 API 要求は、常に現在のユーザーのために実行されます。

Outlook REST API のすべてのサブセットに共通な情報の詳細については、「Outlook REST API の使用」を参照してください。

連絡先を取得する

連絡先フォルダーから、連絡先のコレクションまたは個々の連絡先を取得できます。

最低限必要なスコープ

以下のいずれか:

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	文字列	特定のフォルダーから連絡先を取得している場合は、連絡先フォルダー ID です。

注意

既定では、応答内の各連絡先にそのプロパティがすべて含まれます。最適なパフォーマンスを得るために必要なプロパティのみを指定する場合は、$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

連絡先 ID を使用して連絡先を取得します。

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

必須パラメーター	型	説明
URL パラメーター
contact_id	文字列	連絡先 ID。

応答の種類

要求された連絡先です。

要求のサンプル

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

連絡先と連絡先フォルダーを同期する

ローカルの連絡先の一覧とサーバーの連絡先を同期できます。 Contactssynchronization はフォルダーごとの操作であり、たとえばルート連絡先フォルダーのすべての連絡先を同期できます。その他の連絡先フォルダーがある場合は、各フォルダーを個別に同期する必要があります。

同期は、完全同期のみサポートしています。各要求には、指定したフォルダー内のすべての連絡先が返されます。

通常、連絡先フォルダーを同期するには、2 つ以上の GET 要求が必要です。GET 要求は連絡先を取得すると同じ方法で実行できますが、次の要求ヘッダーを追加する必要があります。

すべての同期要求で、Prefer: odata.track-changes ヘッダーを指定する必要があります。
Prefer: odata.maxpages={n} ヘッダーを指定して、要求ごとに返される連絡先の最大数を指定することができます。

2 番目以降の GET 要求は、前の応答で受信した deltaToken または skipToken のいずれかを含むため、最初の GET 要求とは異なります。

同期要求に対する最初の応答では、常に deltaToken が返されます追加の連絡先がある場合は、2 番目の GET 要求には常に deltaToken を使用します。2 番目の要求は、追加の連絡先、および他にも連絡先がある場合は 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}

必須パラメーター	型	説明
ヘッダーパラメーター
優先	odata.track-changes	要求が同期要求であることを示します。
優先	odata.maxpagesize	各応答で返される連絡先の数を設定します。
URL・パラメーター
folderName	文字列	同期するフォルダーの名前。
odata.deltaLink	文字列	前回フォルダーが同期されたことを示すトークン。
odata.skiptoken	文字列	ダウンロードするメッセージがまだあることを示すトークン。

応答の種類

要求された連絡先と、サーバーからの連絡先データの追加ページを要求し、増分同期を要求するために使用する deltaToken を含むコレクションです。返された連絡先の数が odata.maxpagesize ヘッダーで指定した値より多い場合、応答は複数のページで返されます。

応答には Preference-Applied: odata.track-changes ヘッダーが含まれます。サポートされていないリソースを同期しようとすると、応答でこのヘッダーが返されません。エラーを回避するには、応答を処理する前にこのヘッダーを確認します。

注意

既定では、応答に指定された連絡先のすべてのプロパティが含まれます。最適なパフォーマンスを得るために必要なプロパティのみを指定する場合は、$selectを使用します。 Id プロパティは常に返されます。 $filter、$orderby、$search、または $top は使用しないでください。これらは連絡先または連絡先フォルダーの同期ではサポートされません。詳細については、「OData クエリパラメーター」を参照してください。

例

完全な同期の最初の要求:

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

次のヘッダーが含まれています。

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

完全な同期要求に続くサーバーへの 2 番目の要求です。

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

次のヘッダーが含まれています。

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

追加ページのある、サーバーからの 2 番目の応答です。

ヘッダー

Preference-Applied: odata.track-changes

本文

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

ペイロードメッセージ

すべての連絡先が送信された場合の、2 番目以降のサーバーからの応答です。

ヘッダー

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	文字列	特定の連絡先フォルダーに連絡先を作成する場合は連絡先フォルダー ID です。
本文のパラメーター
GivenName	文字列	連絡先の名前。

要求本文に GivenName パラメーターと任意の書き込み可能な連絡先プロパティを指定します。

要求のサンプル

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

応答の種類

新しい連絡先です。

連絡先を更新する

連絡先のプロパティを変更します。

連絡先を更新する

連絡先を更新する

最低限必要なスコープ

以下のいずれか:

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

要求本文に任意の書き込み可能な連絡先プロパティを指定します。指定したプロパティのみが変更されます。

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

必須パラメーター	型	説明
URL パラメーター
contact_id	文字列	連絡先 ID。

要求のサンプル

次の例では、連絡先の住所とフォローアップフラグを設定します。

注意

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

応答の種類

更新された連絡先です。

連絡先を削除する

連絡先を削除します。削除した内容を回復できない可能性があります。

詳細については、Exchange で EWS を使用して要素を削除するを参照してください。

連絡先を削除する

連絡先を削除する

最低限必要なスコープ

以下のいずれか:

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

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

必須パラメーター	型	説明
URL パラメーター
contact_id	文字列	連絡先 ID。

要求のサンプル

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	文字列	特定の連絡先フォルダーから連絡先フォルダーを取得している場合は、連絡先フォルダー ID です。

要求のサンプル

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

連絡先フォルダー ID を使用して連絡先フォルダーを取得します。

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

注意

パラメーターのフィルタリング、並べ替え、およびページングについては、「OData クエリパラメーター」を参照してください。

必須パラメーター	型	説明
URL・パラメーター
contact_folder_id	文字列	連絡先フォルダー ID。

要求のサンプル

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	文字列	サインインしているユーザーの特定の連絡先を指定する ID です。

要求のサンプル

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

応答データ

要求した写真のバイナリデータが含まれています。HTTP 応答コードは 200 です。

この操作では、Exchange Online で連絡先に連絡先の写真がまだない場合に、HTTP 404 を返します。

連絡先の写真のメタデータを取得する

最低限必要なスコープ

以下のいずれか:

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

コンテンツの種類、幅および高さがピクセル単位で含まれている連絡先の写真のメタデータを取得します。

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

必須パラメーター	型	説明
URL パラメーター
contact_id	文字列	サインインしているユーザーの特定の連絡先を指定する ID です。

要求のサンプル

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	文字列	サインインしているユーザーの特定の連絡先を指定する ID です。

要求のサンプル

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

要求の本文に、写真のバイナリデータを含めます。

応答データ

成功した要求は、HTTP 200 を返します。

次の手順

アプリケーション開発を開始する準備ができている方にも、単に詳しい情報を必要としている方にも、最適なコンテンツをご用意しています。

メール、予定表、および連絡先 REST API の使用を開始します。
サンプルについては、こちらをご覧ください。

Office 365 プラットフォームの使い方の詳細については、次のリンク先をご覧ください。

次の方法で共有

Outlook の連絡先 REST API リファレンス (ベータ版)

連絡先 API のすべての操作

連絡先の操作

連絡先フォルダーの操作

連絡先の写真の操作

関連項目

連絡先 REST API の使用

認証

API のバージョン

対象ユーザー

連絡先を取得する

最低限必要なスコープ

連絡先のコレクションを取得する

要求のサンプル

応答のサンプル

応答の種類

連絡先を取得する

最低限必要なスコープ

応答の種類

要求のサンプル

応答のサンプル

要求のサンプル

応答のサンプル

連絡先と連絡先フォルダーを同期する

最低限必要なスコープ

応答の種類

例

連絡先を作成する

連絡先を作成する

最低限必要なスコープ

要求のサンプル

応答のサンプル

応答の種類

連絡先を更新する

連絡先を更新する

最低限必要なスコープ

要求のサンプル

応答のサンプル

要求のサンプル

応答のサンプル

応答の種類

連絡先を削除する

連絡先を削除する

最低限必要なスコープ

要求のサンプル

応答のサンプル

連絡先フォルダーの取得

連絡先フォルダーのコレクションを取得する

最低限必要なスコープ

要求のサンプル

応答のサンプル

応答の種類

連絡先フォルダーを取得する

最低限必要なスコープ

要求のサンプル

応答のサンプル

応答の種類

連絡先の写真とメタデータを取得する

連絡先の写真を取得する

最低限必要なスコープ

要求のサンプル

応答データ

連絡先の写真のメタデータを取得する

最低限必要なスコープ

要求のサンプル

応答データのサンプル

連絡先の写真を設定する

最低限必要なスコープ

要求のサンプル

応答データ

次の手順

その他のリソース