このページは Cloud Translation API によって翻訳されました。

バッチリクエスト

ここでは、複数の API 呼び出しを一括して行い、クライアント側の HTTP 接続の回数を減らす方法について説明します。バッチ処理を行うと、ネットワークのラウンドトリップを減らし、スループットを増やすことで、アプリケーションの効率を高めることができます。

概要

クライアントが接続するたびに、一定量のオーバーヘッドが発生します。Google スプレッドシート API はバッチ処理をサポートしているため、クライアントは複数のリクエストオブジェクト（それぞれが実行するリクエストの種類を 1 つ指定）を 1 つのバッチリクエストにまとめることができます。バッチリクエストでは、複数のサブリクエストを 1 つのサーバー呼び出しにまとめ、1 つのレスポンスを取得することでパフォーマンスを向上させることができます。

複数のリクエストは常にバッチで処理することをおすすめします。バッチ処理を使用できる状況の例をいくつか示します。

API の使用を開始したばかりで、アップロードするデータが大量にある。
複数のオブジェクトのメタデータまたはプロパティ（書式など）を更新する必要があります。
多くのオブジェクトを削除する必要がある。

上限、承認、依存関係に関する考慮事項

バッチアップデートを使用する際に考慮すべきその他の項目は次のとおりです。

すべてのサブリクエストを含む各バッチリクエストは、使用量上限に対して 1 件の API リクエストとしてカウントされます。
バッチリクエストは 1 回認証されます。この単一の認証は、リクエスト内のすべてのバッチ更新オブジェクトに適用されます。
サーバーは、バッチリクエストに表示されるのと同じ順序でサブリクエストを処理します。後続のサブリクエストは、前のサブリクエストで行われたアクションに依存する場合があります。たとえば、同じバッチリクエストで、既存のドキュメントにテキストを挿入してからスタイル設定できます。

バッチリクエストの詳細

バッチリクエストは、1 つの batchUpdate メソッド呼び出しと複数のサブリクエストで構成されます。たとえば、スプレッドシートの追加とフォーマット設定などです。

各リクエストは適用前に検証されます。バッチ更新内のすべてのサブリクエストはアトミックに適用されます。つまり、いずれかのリクエストが無効な場合、更新全体が失敗し、（依存している可能性のある）変更は適用されません。

一部のリクエストでは、適用されたリクエストに関する情報がレスポンスで返されます。たとえば、オブジェクトを追加するバッチ更新リクエストはすべてレスポンスを返すため、新しく追加されたオブジェクトのメタデータ（ID やタイトルなど）にアクセスできます。

この方法では、複数のサブリクエストを含む 1 つの API バッチ更新リクエストを使用して、Google ドキュメント全体を作成できます。

バッチリクエストの形式

リクエストは、複数のネストされたサブリクエストを含む単一の JSON リクエストで、1 つの必須プロパティ requests があります。リクエストは、個々のリクエストの配列で構成されます。各リクエストは、JSON を使用してリクエストオブジェクトを表し、そのプロパティを格納します。

バッチレスポンスの形式

バッチリクエストのレスポンスの形式は、リクエストの形式に似ています。サーバーのレスポンスには、単一のレスポンスオブジェクトの完全なレスポンスを含めます。

メインの JSON オブジェクトのプロパティの名前は replies です。レスポンスは配列で返されます。各リクエストに対するレスポンスは、対応するリクエストと同じインデックス順序で返されます。一部のリクエストにはレスポンスがなく、その配列インデックスのレスポンスは空になります。

例

次の例は、Sheets API でバッチ処理を使用する方法を示しています。

リクエスト

このバッチリクエストの例は、次の方法を示しています。

AddSheetRequest を使用して、既存のスプレッドシートに sheetId が 12345 のシートを追加します。
UpdateCellsRequest を使用して、セル A1 から新しいシートにデータを追加します。
新しいシートに namedRange またはフィルタビューを追加します。

リクエストにシート ID を追加すると、同じ API 呼び出し内の他のサブリクエストでシート ID を使用できます。これにより、書き込み、読み取り、書き込みのサイクルが発生しないため、パフォーマンスが向上します。

バッチ更新リクエストの種類のリスト（さまざまなカテゴリにグループ化）については、バッチ更新オペレーションの表をご覧ください。

{
   "requests":[
      {
         "addSheet":{
            "properties":{
               "sheetId":123456
            }
         }
      },
      {
         "updateCells":{
            "start":{
               "sheetId":123456
            },
            "rows":[
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"hello"
                        }
                     }
                  ]
               },
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"world"
                        }
                     }
                  ]
               }
            ],
            "fields":"userEnteredValue"
         }
      },
      {
         "addNamedRange":{
            "namedRange":{
               "name":"newRange",
               "range":{
                  "sheetId":123456,
                  "endRowIndex":2
               }
            }
         }
      }
   ]
}

レスポンス

このバッチレスポンスの例には、バッチリクエスト内の各サブリクエストがどのように適用されたかに関する情報が表示されます。UpdateCellsRequest にはレスポンスが含まれていないため、[1] の配列のインデックス値は空の中かっこで構成されています。

"replies":[
   {
      "addSheet":{
         "properties":{
            "sheetId":123456,
            "title":"Sheet3",
            "index":2,
            "sheetType":"GRID",
            "gridProperties":{
               "rowCount":1000,
               "columnCount":26
            }
         }
      }
   },
   {
      
   },
   {
      "addNamedRange":{
         "namedRange":{
            "namedRangeId":"2104325079",
            "name":"newRange",
            "range":{
               "sheetId":123456,
               "startRowIndex":0,
               "endRowIndex":2,
               "startColumnIndex":0,
               "endColumnIndex":26
            }
         }
      }
   }
]

バッチ リクエスト

概要