バッチでの Outlook REST 要求の送信 (ベータ版)

適用対象: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

バッチ処理を使用すると、複数の Outlook REST 要求を 1 つの HTTP バッチ要求にまとめられるようになり、HTTP 接続の数とオーバーヘッドを削減できます。バッチに含まれる要求によって、サインインしているユーザーのデータにアクセスされます。このユーザーは、Office 365 の Azure Active Directory または Microsoft アカウント (Hotmail.com、Live.com、MSN.com、Outlook.com、または Passport.com) でセキュリティ保護されています。

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

概要

REST 要求を実行するには、クライアントとサーバー間に HTTP 接続が必要であり、一定のオーバーヘッドが生じます。 バッチ処理を使用し、同じコンテキストの複数の REST API 呼び出しを $batch エンドポイントに対する 1 つの HTTP POST 要求にまとめることで、接続のオーバーヘッドを軽減できます。

たとえば、次のようにme コンテキストの API 呼び出しをまとめることができます。

POST https://outlook.office.com/api/beta/me/$batch

1 つのバッチ要求には、最大 20 の個別の REST API 呼び出しを含めることができます。この呼び出しは、データ クエリ (たとえば、GET) または変更操作 (たとえば、POST) になります。Prefer ヘッダーを指定することで、1 つまたは複数の REST 呼び出しが失敗したときでも、バッチが継続されるようになります。

バッチ処理は、特に大量のデータを同期する場合に役立ちます。同じバッチに含まれる API 呼び出しは、同一メールボックスに属している異なるリソース (メッセージやイベントなど) にアクセスできます。

20 件以上の呼び出しが必要な場合や、呼び出しの完了する順序が問題になる場合は、複数のバッチ要求を使用してください。

例

単純な例は、バッチ処理を最もわかりやすく示します。次に示すバッチ要求は、me のコンテキストで 2 つの Outlook REST API 呼び出しを 1 つのバッチにまとめています。

1. サインインしているユーザーのすべてイベントを GET する
2. POST してメッセージを送信する。

バッチ要求

POST https://outlook.office.com/api/beta/me/$batch HTTP/1.1

Authorization: Bearer aGFwcHlnQGRr==
Host: outlook.office.com
Content-Type: multipart/mixed; boundary=batch_myBatchId

--batch_myBatchId
Content-Type: application/http
Content-Transfer-Encoding: binary

GET /api/beta/me/events?$select=subject,organizer HTTP/1.1

--batch_myBatchId
Content-Type: application/http
Content-Transfer-Encoding: binary

POST /api/beta/me/sendmail HTTP/1.1
Content-Type: application/json

{
  "Message": {
    "Subject": "Meet for lunch?",
    "Body": {
      "ContentType": "Text",
      "Content": "The new cafeteria is open."
    },
    "ToRecipients": [
      {
        "EmailAddress": {
          "Address": "rufus@contoso.com"
        }
      }
    ]
  }
}

--batch_myBatchId--
 

バッチ応答

バッチ応答には、バッチ要求と個別の呼び出しごとに個別の応答コードと本文が含まれています (該当する場合)。

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Length: 786

--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Events(Subject,Organizer)",
    "value":[
        {
            "@odata.id":"https://outlook.office.com/api/beta/Users('cd209b0b-3f83-4c35-82d2-d88a61820480@8b5d41d8-b1af-495e-b871-8bbd867ba67a')/Events('AAMkAGI1AAAt9AHkAAA=')",
            "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAALfZeSA==\"",
            "Id":"AAMkAGI1AAAt9AHkAAA=",
            "Subject":"Let's go for lunch",
            "Organizer":{
                "EmailAddress":{
                    "Name":"Dana Swope",
                    "Address":"danas@contoso.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id":"https://outlook.office.com/api/beta/Users('cd209b0b-3f83-4c35-82d2-d88a61820480@8b5d41d8-b1af-495e-b871-8bbd867ba67a')/Events('AAMkAGI1AAAtCq6LAAA=')",
            "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAALQzodA==\"",
            "Id":"AAMkAGI1AAAtCq6LAAA=",
            "Subject":"Prep for customer visit",
            "Organizer":{
                "EmailAddress":{
                    "Name":"Dana Swope",
                    "Address":"danas@contoso.onmicrosoft.com"
                }
            }
        }
    ]
}
--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 202 Accepted

--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a--

エンドポイント URL

2 つのコンテキストのいずれかについて、$batch エンドポイントで POST を実行できます。

• サインイン ユーザー me の場合:

  POST https://outlook.office.com/api/beta/me/$batch HTTP/1.1
  

• user_id がユーザー ID かユーザーのメール アドレスになる特定のユーザーの場合:

  POST https://outlook.office.com/api/beta/users('{user_id}')/$batch
  

$batch エンドポイントへの POST 要求でコンテキストを確立したら、同じバッチ要求に含まれているすべての REST API 呼び出しを同じコンテキストに適用する必要があります。

API のバージョン

バッチ要求は、プレビューから一般提供 (GA) の状態にレベル上げされています。Outlook REST API の v2.0 とベータのバージョンでサポートされます。

このバッチの REST 呼び出しと同じホストとバージョンをバッチ要求に指定する必要があります。

対象ユーザー

同一メールボックスに対する Outlook REST API 呼び出しは、1 つのバッチにグループ化できます。このメールボックスは、Office 365 と Outlook.com のどちらでもかまいません。バッチ処理される一連の要求で複数のメールボックスにアクセスしようとすると、例外が発生します。

認証

複数の Outlook REST API 呼び出しを個別の要求として送信する場合と同様に、Authorization ヘッダーには有効なアクセス トークンを含める必要があります。バッチ要求の場合、このヘッダーを指定すると、アクセス トークンによってバッチに含まれるすべての呼び出しに必要なアクセス許可が提供されます。バッチに含まれる特定の呼び出しが別のアクセス トークンを必要とする場合は、その呼び出しにアクセス トークンを指定することもできます。

アクセス トークンを取得するには、アプリを登録して識別し、適切な承認を取得する必要があります。効率化された登録と承認のオプションに関する詳細情報を参照してください。要求のバッチ処理についての理解を深める際には、この点に注意してください。

バッチ要求のヘッダー

バッチ要求ごとに、次に示すヘッダーを含めます。

Host: outlook.office.com
Content-Type: multipart/mixed; boundary=batch_<batchId> 

{batchId} はバッチを識別するものであり、バッチ内の要求を区切るために使用されます。これは、GUID または任意の識別文字列のどちらかになります。

適切な場所に、その他のヘッダーを含めることができます。コンテンツ関連のヘッダー (Content-Type など) を除いて、バッチ要求に含まれるヘッダーは、通常、バッチ内のすべての操作に適用されます。バッチ要求と、そのバッチに含まれる特定の操作の両方にヘッダーを指定すると、その操作には後者が優先されて操作に適用されます。

バッチ要求の本文

バッチ内の各操作は、次に示すヘッダー行で始まります。

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

バッチ内の最後の操作は、次に示す行で終了します。

--batch_{batchId}--
 

バッチ要求本文の形式

形式に関する次の要件にご注意ください。これに従わないと、バッチ要求が失敗する場合や、想定する応答が返されない場合があります。

• バッチ境界区切り記号の前に必ず追加の改行を含めます (バッチ処理する 2 つの GET 操作を持つ次の要求本文を参照)。
• 特に、最初の例のバッチ要求と似た、末尾が POST 要求のバッチの場合は、最後のバッチ区切り記号 --batch_{batchId}-- の_後_で必ず改行します。

バッチ要求本文のその他の例については、「Batch Processing (OData Version 3.0)」を参照してください。

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

GET  /api/v2.0/me/messages    HTTP/1.1

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

GET  /api/v2.0/me/events    HTTP/1.1

--batch_{batchId}--
 

バッチに含まれる操作

1 つのバッチ要求に、最大 20 件の操作を指定できます。

バッチ内の操作は、データ クエリ、変更、アクション、または関数呼び出しの要求のいずれかになります。バッチに含まれる操作ごとに完全な URL を繰り返す必要も、すべてのヘッダーを宣言する必要もありませんが、ある操作に特定のヘッダーと要求本文が必要な場合は、それらが含まれていることをご確認ください。

バッチでサポートされている要求の形式

前述のとおり、バッチ処理する一連の要求全体で、ホスト、バージョン、コンテキストは一貫性が保たれていなければなりません。同じバッチに含まれる要求では、次の 3 つの形式を混在させることができます。以下の例では、$batch エンドポイントへの POST 要求が次のようであるとします。

POST https://outlook.office.com/api/beta/me/$batch HTTP/1.1

絶対 URL

URL にホスト、バージョン、コンテキストを含めます。次に例を示します。

GET https://outlook.office.com/api/beta/me/messages?$select=subject,sender HTTP/1.1 

ホストからの相対 URL

バッチ要求で指定したホストからの相対 URL を含めます。バッチ処理する要求ごとにホストを繰り返すことはしませんが、バージョンとコンテキストは含めます。次に例を示します。

GET /api/beta/me/messages?$select=subject,sender HTTP/1.1

バッチからの相対 URL

この形式では、バッチ要求でホスト、バージョン、コンテキストを繰り返しません。次に例を示します。

GET messages?$select=subject,sender HTTP/1.1

バッチ要求の処理

1 つのバッチ要求は、それ自体が 1 つの要求として処理され、それ自体の応答コードを返します。 正しいヘッダーを指定した適切なバッチ要求は、HTTP 200 OK を返します。 ただし、これはバッチ内のすべての要求が成功したことを示しません。

バッチ要求本文内のバッチ要求は、別々に処理され、独自の応答コードおよび応答の本文とエラー メッセージを返します。

サーバーは、バッチ内の操作を任意の順序で実行することがあります。特定の順序で操作を実行する必要がある場合は、その操作を同一のバッチに含めてはいけません。その代わりに、1 つの操作を単独で送信し、次のものを送信するまで応答を待機します。

既定では、処理は最初にエラーを返した操作の時点で停止します。次に示すヘッダーを指定することで、処理はエラーを無視して、バッチ内で後続の操作を継続するようになります。

Prefer: odata.continue-on-error

次の手順

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

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

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

• Outlook デベロッパー センターの Outlook REST API
• Office 365 プラットフォームでの開発の概要
• Office 365 のアプリ認証とリソース承認
• Office 365 API にアクセスできるようにアプリを手動で Azure AD に登録する
• メール REST API リファレンス
• 予定表 REST API リファレンス
• 連絡先 REST API リファレンス
• タスク REST API (プレビュー)
• メール、予定表、連絡先、タスク REST API のリソース リファレンス
• Office 365 データ拡張機能 REST API リファレンス
• People API リファレンス (プレビュー)
• 通知 REST API リファレンス
• ユーザー写真 REST API リファレンス