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

バッチリクエスト

このドキュメントでは、複数の API 呼び出しをバッチ処理して、クライアントが確立する必要がある接続の数です。バッチ処理では、アプリケーションのネットワークのラウンドトリップを減らしてスループットを向上できます

概要

クライアントで接続を行うたびに、ある程度のオーバーヘッドが発生します。 Google Sheets API はバッチ処理をサポートしており、これによりクライアントは複数のリクエストオブジェクト。各オブジェクトは、実行するリクエストの種類を 1 つ指定し、単一のバッチリクエストにまとめることができます。バッチリクエストは次の処理によってパフォーマンスを向上させます。複数のサブリクエストをサーバーへの 1 回の呼び出しにまとめ、返すことができます

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

API を使い始めたばかりで、アップロードするデータが大量にあります。
メタデータや、フォーマットなどのプロパティを複数の説明します。
多くのオブジェクトを削除する必要がある。

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

バッチ更新を採用する際に考慮すべきその他の項目は次のとおりです。

各バッチリクエスト（すべてのサブリクエストを含む）は、1 つの API としてカウントされます。使用量上限に対するリクエスト。
バッチリクエストは 1 回認証されます。この単一の認証がリクエスト内のすべてのバッチアップデートオブジェクトに対して適用されます。
サーバーは、サブリクエストを使用します。後のサブリクエストは、セッション中に実行されたアクションに依存する以前のサブリクエストを実行します。たとえば、同じバッチリクエストで、既存のドキュメントにテキストを挿入してスタイルを設定する。

バッチリクエストの詳細

バッチリクエストは 1 回の batchUpdate メソッド呼び出しで構成されます。スプレッドシートの追加や書式設定など、複数のサブリクエストを持つことができます。

各リクエストは、適用前に検証されます。バッチ内のすべてのサブリクエストアトミックに適用されます。つまり、いずれかのリクエストが有効でない場合、アップデート全体が失敗し、アップデートに適用されます。

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

このアプローチでは、1 つの API で Google ドキュメント全体を作成できます。バッチアップデートリクエストを実行できます。

バッチリクエストの形式

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

バッチレスポンスの形式

バッチリクエストのレスポンス形式は、リクエスト形式に従って処理します。サーバーのレスポンスには、リクエストに対する 1 つのレスポンスオブジェクト。

メインの 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
            }
         }
      }
   }
]

バッチ リクエスト

概要