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

バッチリクエスト

このドキュメントでは、複数の API 呼び出しを一括して行い、クライアント側の接続の回数を減らす方法について説明します。バッチ処理により、ネットワークの往復回数を減らし、スループットを増やすことで、アプリケーションの効率を向上させることができます。

概要

クライアントが確立する各接続には、ある程度のオーバーヘッドが発生します。Google Sheets API はバッチ処理をサポートしており、クライアントは複数のリクエストオブジェクト（それぞれが実行する単一タイプのリクエストを指定）を 1 つのバッチリクエストに配置できます。バッチリクエストを使用すると、複数のサブリクエストを 1 回のサーバー呼び出しに結合し、1 回のレスポンスを取得することで、パフォーマンスを向上させることができます。

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

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

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

バッチ更新を使用する際に考慮すべきその他の項目を以下に示します。

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

バッチリクエストの詳細

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

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

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

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

バッチリクエストの形式

リクエストは、複数のネストされたサブリクエストを含む単一の JSON リクエストです。必須のプロパティは 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
            }
         }
      }
   }
]

バッチ リクエスト コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

概要