Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

スプレッドシートを更新する

このドキュメントでは、 spreadsheets.batchUpdate メソッドを spreadsheetsリソースで使用する際の基本について説明します。

スプレッドシートには、セルに含まれる値データ以外にも、次のようなさまざまな種類のデータが含まれています。

サイズ
セルの書式と罫線
名前付き範囲
保護されている範囲
条件付き書式

これらは、スプレッドシートの表示と動作を制御する多くの種類のデータの一部です。spreadsheets.batchUpdate メソッドを使用すると、これらのスプレッドシートの詳細を更新できます。変更はバッチでグループ化されるため、1 つのリクエストが失敗した場合、他の（依存する可能性のある）変更は書き込まれません。

セル値データを読み書きする必要がある場合は、 spreadsheets.values リソースをセル値の読み書きで説明されているように使用することもできます。

オペレーションタイプ

spreadsheets.batchUpdate メソッドでサポートされている特定のオペレーションは、次のオペレーションタイプに分類できます。

カテゴリ	説明
追加（複製）	新しいオブジェクトを追加します（複製リクエストのように、古いオブジェクトに基づいて追加されることもあります）。
更新（設定）	オブジェクトの特定のプロパティを更新します。通常、古いプロパティはそのまま残ります（設定リクエストでは、以前のデータが上書きされます）。
削除	オブジェクトを削除します。

次のセクションでは、これらのカテゴリを使用して、特定のオペレーションの動作について説明します。

バッチアップデートオペレーション

spreadsheets.batchUpdate メソッドは、1 つ以上の Request オブジェクトを受け取ります。各オブジェクトは、実行するリクエストの種類を 1 つ指定します。次の表に、リソースオブジェクトとオペレーションタイプごとにグループ化されたバッチアップデートリクエストのタイプを示します。

オブジェクト	追加 / 複製	更新 / 設定	削除
`BandedRange`	AddBandingRequest	UpdateBandingRequest	DeleteBandingRequest
`Borders`		UpdateBordersRequest
`Cells`（値、書式、データ検証など）	InsertRangeRequest	RepeatCellRequest UpdateCellsRequest AppendCellsRequest	DeleteRangeRequest
`ConditionalFormatRule`	AddConditionalFormatRuleRequest	UpdateConditionalFormatRuleRequest	DeleteConditionalFormatRuleRequest
`DataSource`	AddDataSourceRequest	UpdateDataSourceRequest RefreshDataSourceRequest CancelDataSourceRefreshRequest	DeleteDataSourceRequest
`DataValidationRule`		SetDataValidationRequest
`developerMetadata`	CreateDeveloperMetadataRequest	UpdateDeveloperMetadataRequest	DeleteDeveloperMetadataRequest
`Dimension`（`DimensionRange` を含む）	InsertDimensionRequest AppendDimensionRequest	UpdateDimensionPropertiesRequest MoveDimensionRequest AutoResizeDimensionsRequest	DeleteDimensionRequest
`DimensionGroup`	AddDimensionGroupRequest	UpdateDimensionGroupRequest	DeleteDimensionGroupRequest
`EmbeddedChart`	AddChartRequest	UpdateChartSpecRequest UpdateEmbeddedObjectPositionRequest UpdateEmbeddedObjectBorderRequest	DeleteEmbeddedObjectRequest
`FilterView`（`BasicFilter` を含む）	AddFilterViewRequest DuplicateFilterViewRequest	UpdateFilterViewRequest SetBasicFilterRequest	ClearBasicFilterRequest DeleteFilterViewRequest
セルの結合（`MergeType` を含む）	MergeCellsRequest		UnmergeCellsRequest
`NamedRange`	AddNamedRangeRequest	UpdateNamedRangeRequest	DeleteNamedRangeRequest
`ProtectedRange`	AddProtectedRangeRequest	UpdateProtectedRangeRequest	DeleteProtectedRangeRequest
`Sheets`	AddSheetRequest DuplicateSheetRequest	UpdateSheetPropertiesRequest	DeleteSheetRequest
`Slicer`	AddSlicerRequest	UpdateSlicerSpecRequest
`SpreadsheetProperties`		UpdateSpreadsheetPropertiesRequest
`Table`	AddTableRequest	UpdateTableRequest	DeleteTableRequest

データ操作リクエスト

データを操作するためのユーザー操作を模倣するリクエストもあります。

リクエスト	説明
`AutoFillRequest`	既存のデータに基づいて、より多くのデータを自動的に入力します。
`CopyPasteRequest`	ある領域からデータをコピーして別の領域に貼り付けます。
`CutPasteRequest`	ある領域からデータを切り取って別の領域に貼り付けます。
`DeleteDuplicatesRequest`	セル範囲の指定された列に重複する値を含む行を削除します。
`FindReplaceRequest`	一部のテキストを検索して、別のテキストに置き換えます。
`PasteDataRequest`	データを（HTML または区切り文字付き）シートに貼り付けます。
`RandomizeRangeRequest`	範囲内の行の順序をランダム化します。
`SortRangeRequest`	範囲内のデータを並べ替えます。
`TextToColumnsRequest`	テキストの列を複数のテキスト列に変換します。
`TrimWhitespaceRequest`	セルから空白文字（スペース、タブ、改行など）を削除します。

Google スプレッドシートのセルと行の上限について詳しくは、Google ドライブに保存できるファイルをご覧ください。

フィールドマスクを使用して特定のフィールドを更新する

多くの更新リクエストには FieldMaskが必要です。フィールドマスクは、オブジェクト内のどのフィールドを更新するかを示すために使用されるフィールドのカンマ区切りリストです。他のフィールドは変更されません。フィールドマスクを使用すると、リクエストで指定されていないフィールドが誤って上書きされるのを防ぐことができます。

フィールドマスクの詳細については、フィールドマスクを使用して更新するをご覧ください。

次のコードサンプルは、 UpdateSpreadsheetPropertiesRequest を使用してスプレッドシートのタイトルのみを更新する方法を示しています。

リクエスト

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate

リクエストの本文

{
  "requests": [{
      "updateSpreadsheetProperties": {
          "properties": {"title": "TITLE"},
          "fields": "title"
      }
  }]
}

TITLE は、スプレッドシートの新しいタイトルに置き換えます。

バッチアップデートレスポンス

スプレッドシートを更新する際に、一部のリクエストでレスポンスが返されることがあります。これらは配列で返され、各レスポンスは対応するリクエストと同じインデックスを占有します。レスポンスがないリクエストもあり、その場合はレスポンスが空になります。

通常、「追加」リクエストには、追加されたオブジェクトの ID などの情報を返すレスポンスがあります。サポートされているレスポンスの一覧については、 Responsesをご覧ください。

コードサンプル: スプレッドシートのバッチアップデート

次のコードサンプルは、次の操作を行う方法を示しています。

title 変数を使用して、スプレッドシートのタイトルを更新します。
find 変数と replacement 変数を使用して、スプレッドシート内のセル値を検索して置換します。

Apps Script

sheets/api/spreadsheet_snippets.gs

GitHub で表示

/**
 * Updates the specified sheet using advanced sheet services
 * @param {string} spreadsheetId id of the spreadsheet to be updated
 * @param {string} title name of the sheet in the spreadsheet to be updated
 * @param {string} find string to be replaced
 * @param {string} replacement the string to replace the old data
 * @returns {*} the updated spreadsheet
 */
Snippets.prototype.batchUpdate = (spreadsheetId, title, find, replacement) => {
  // This code uses the Sheets Advanced Service, but for most use cases
  // the built-in method SpreadsheetApp.getActiveSpreadsheet()
  //     .getRange(range).setValues(values) is more appropriate.

  try {
    // Change the spreadsheet's title.
    const updateSpreadsheetPropertiesRequest =
      Sheets.newUpdateSpreadsheetPropertiesRequest();
    updateSpreadsheetPropertiesRequest.properties =
      Sheets.newSpreadsheetProperties();
    updateSpreadsheetPropertiesRequest.properties.title = title;
    updateSpreadsheetPropertiesRequest.fields = "title";

    // Find and replace text.
    const findReplaceRequest = Sheets.newFindReplaceRequest();
    findReplaceRequest.find = find;
    findReplaceRequest.replacement = replacement;
    findReplaceRequest.allSheets = true;

    const requests = [Sheets.newRequest(), Sheets.newRequest()];
    requests[0].updateSpreadsheetProperties =
      updateSpreadsheetPropertiesRequest;
    requests[1].findReplace = findReplaceRequest;

    const batchUpdateRequest = Sheets.newBatchUpdateSpreadsheetRequest();
    batchUpdateRequest.requests = requests;

    // Add additional requests (operations)
    const result = Sheets.Spreadsheets.batchUpdate(
      batchUpdateRequest,
      spreadsheetId,
    );
    return result;
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", err.message);
  }
};

Java

sheets/snippets/src/main/java/BatchUpdate.java

GitHub で表示

import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.sheets.v4.Sheets;
import com.google.api.services.sheets.v4.SheetsScopes;
import com.google.api.services.sheets.v4.model.BatchUpdateSpreadsheetRequest;
import com.google.api.services.sheets.v4.model.BatchUpdateSpreadsheetResponse;
import com.google.api.services.sheets.v4.model.FindReplaceRequest;
import com.google.api.services.sheets.v4.model.FindReplaceResponse;
import com.google.api.services.sheets.v4.model.Request;
import com.google.api.services.sheets.v4.model.SpreadsheetProperties;
import com.google.api.services.sheets.v4.model.UpdateSpreadsheetPropertiesRequest;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

/* Class to demonstrate the use of Spreadsheet Batch Update API */
public class BatchUpdate {
  /**
   * Updates spreadsheet's title and cell values.
   *
   * @param spreadsheetId - Id of the spreadsheet.
   * @param title         - New title of the spreadsheet.
   * @param find          - Find cell values
   * @param replacement   - Replaced cell values
   * @return response metadata
   * @throws IOException - if credentials file not found.
   */
  public static BatchUpdateSpreadsheetResponse batchUpdate(String spreadsheetId,
                                                           String title,
                                                           String find,
                                                           String replacement)
      throws IOException {
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Collections.singleton(SheetsScopes.SPREADSHEETS));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Create the sheets API client
    Sheets service = new Sheets.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Sheets samples")
        .build();

    List<Request> requests = new ArrayList<>();
    BatchUpdateSpreadsheetResponse response = null;
    try {
      // Change the spreadsheet's title.
      requests.add(new Request()
          .setUpdateSpreadsheetProperties(new UpdateSpreadsheetPropertiesRequest()
              .setProperties(new SpreadsheetProperties()
                  .setTitle(title))
              .setFields("title")));
      // Find and replace text.
      requests.add(new Request()
          .setFindReplace(new FindReplaceRequest()
              .setFind(find)
              .setReplacement(replacement)
              .setAllSheets(true)));

      BatchUpdateSpreadsheetRequest body =
          new BatchUpdateSpreadsheetRequest().setRequests(requests);
      response = service.spreadsheets().batchUpdate(spreadsheetId, body).execute();
      FindReplaceResponse findReplaceResponse = response.getReplies().get(1).getFindReplace();

      System.out.printf("%d replacements made.", findReplaceResponse.getOccurrencesChanged());
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      GoogleJsonError error = e.getDetails();
      if (error.getCode() == 404) {
        System.out.printf("Spreadsheet not found with id '%s'.\n", spreadsheetId);
      } else {
        throw e;
      }
    }
    return response;
  }
}

JavaScript

sheets/snippets/sheets_batch_update.js

GitHub で表示

function batchUpdate(spreadsheetId, title, find, replacement, callback) {
  const requests = [];
  // Change the spreadsheet's title.
  requests.push({
    updateSpreadsheetProperties: {
      properties: {
        title: title,
      },
      fields: 'title',
    },
  });
  // Find and replace text.
  requests.push({
    findReplace: {
      find: find,
      replacement: replacement,
      allSheets: true,
    },
  });
  try {
    // Add additional requests (operations) ...
    const batchUpdateRequest = {requests: requests};
    gapi.client.sheets.spreadsheets.batchUpdate({
      spreadsheetId: spreadsheetId,
      resource: batchUpdateRequest,
    }).then((response) => {
      const findReplaceResponse = response.result.replies[1].findReplace;
      console.log(`${findReplaceResponse.occurrencesChanged} replacements made.`);
      if (callback) callback(response);
    });
  } catch (err) {
    document.getElementById('content').innerText = err.message;
    return;
  }
}

Node.js

sheets/snippets/sheets_batch_update.js

GitHub で表示

import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Performs a batch update on a spreadsheet.
 * Updates the spreadsheet title and finds and replaces a string.
 * @param {string} spreadsheetId The ID of the spreadsheet to update.
 * @param {string} title The new title for the spreadsheet.
 * @param {string} find The string to find.
 * @param {string} replacement The string to replace the found string with.
 * @return {Promise<object>} The response from the batch update.
 */
async function batchUpdate(spreadsheetId, title, find, replacement) {
  // Authenticate with Google and get an authorized client.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/spreadsheets',
  });

  // Create a new Sheets API client.
  const service = google.sheets({version: 'v4', auth});

  // Create a list of requests to be executed in the batch update.
  const requests = [];

  // Request to change the spreadsheet's title.
  requests.push({
    updateSpreadsheetProperties: {
      properties: {
        title,
      },
      fields: 'title',
    },
  });

  // Request to find and replace text.
  requests.push({
    findReplace: {
      find,
      replacement,
      allSheets: true,
    },
  });

  // Add more requests here if needed.

  // Create the batch update request.
  const batchUpdateRequest = {requests};

  // Execute the batch update request.
  const response = await service.spreadsheets.batchUpdate({
    spreadsheetId,
    requestBody: batchUpdateRequest,
  });

  // Get the response from the find and replace request and log the number of occurrences.
  const findReplaceResponse = response.data.replies[1].findReplace;
  console.log(`${findReplaceResponse.occurrencesChanged} replacements made.`);
  return response;
}

PHP

sheets/snippets/src/SpreadsheetBatchUpdate.php

GitHub で表示

<?php
use Google\Client;
use Google\Service\Drive;
use Google\Service\Sheets\BatchUpdateSpreadsheetRequest;

/**
 * to batch update a spreadsheet
 */
function batchUpdate($spreadsheetId, $title, $find, $replacement)
    {   
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
        $client = new Google\Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Google\Service\Drive::DRIVE);
        $service = new Google_Service_Sheets($client);
        try{
            //execute the request
            $requests = [
                new Google_Service_Sheets_Request([
              'updateSpreadsheetProperties' => [
                  'properties' => [
                      'title' => $title
                    ],
                    'fields' => 'title'
              ]
          ]),
          new Google_Service_Sheets_Request([
              'findReplace' => [
                  'find' => $find,
                  'replacement' => $replacement,
                  'allSheets' => true
                  ]
                  ])
                ];
                $batchUpdateRequest = new Google_Service_Sheets_BatchUpdateSpreadsheetRequest([
                    'requests' => $requests
                ]);
        $response = $service->spreadsheets->batchUpdate($spreadsheetId, $batchUpdateRequest);
        $findReplaceResponse = $response->getReplies()[1]->getFindReplace();
        printf("%s replacements made.\n",
        $findReplaceResponse->getOccurrencesChanged());
        return $response;
    }
    catch(Exception $e) {
        // TODO(developer) - handle error appropriately
        echo 'Message: ' .$e->getMessage();
      }
    }

Python

sheets/snippets/sheets_batch_update.py

GitHub で表示

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def sheets_batch_update(spreadsheet_id, title, find, replacement):
  """
  Update the sheet details in batch, the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """

  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member

  try:
    service = build("sheets", "v4", credentials=creds)

    requests = []
    # Change the spreadsheet's title.
    requests.append(
        {
            "updateSpreadsheetProperties": {
                "properties": {"title": title},
                "fields": "title",
            }
        }
    )
    # Find and replace text
    requests.append(
        {
            "findReplace": {
                "find": find,
                "replacement": replacement,
                "allSheets": True,
            }
        }
    )
    # Add additional requests (operations) ...

    body = {"requests": requests}
    response = (
        service.spreadsheets()
        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
        .execute()
    )
    find_replace_response = response.get("replies")[1].get("findReplace")
    print(
        f"{find_replace_response.get('occurrencesChanged')} replacements made."
    )
    return response

  except HttpError as error:
    print(f"An error occurred: {error}")
    return error


if __name__ == "__main__":
  sheets_batch_update("spreadsheet_id", "title", "find", "replacement")

Ruby

sheets/snippets/lib/spreadsheet_snippets.rb

GitHub で表示

requests = []
# Change the name of sheet ID '0' (the default first sheet on every
# spreadsheet)
requests.push({
                update_sheet_properties: {
                  properties: { sheet_id: 0, title: 'New Sheet Name' },
                  fields:     'title'
                }
              })
# Find and replace text
requests.push({
                find_replace: {
                  find:        find,
                  replacement: replacement,
                  all_sheets:  true
                }
              })
# Add additional requests (operations) ...

body = { requests: requests }
result = service.batch_update_spreadsheet(spreadsheet_id, body, {})
find_replace_response = result.replies[1].find_replace
puts "#{find_replace_response.occurrences_changed} replacements made."

スプレッドシートを更新する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

オペレーション タイプ

バッチ アップデート オペレーション

データ操作リクエスト

フィールド マスクを使用して特定のフィールドを更新する

バッチ アップデート レスポンス

コードサンプル: スプレッドシートのバッチ アップデート

Apps Script

Java

JavaScript

Node.js

PHP

Python

Ruby

スプレッドシートを更新する

オペレーションタイプ

バッチアップデートオペレーション

フィールドマスクを使用して特定のフィールドを更新する

バッチアップデートレスポンス

コードサンプル: スプレッドシートのバッチアップデート