名前付き範囲と保護されている範囲

Google Sheets API を使用すると、名前付き範囲または保護されている範囲を作成、変更、削除できます。このページの例は、Sheets API を使用して一般的なスプレッドシート オペレーションを実行する方法を示しています。

これらの例は、言語に依存しない HTTP リクエストの形式で提供されています。Google API クライアント ライブラリを使用してバッチ アップデートをさまざまな言語で実装する方法については、スプレッドシートを更新するをご覧ください。

以下の例では、プレースホルダ SPREADSHEET_ID と SHEET_ID が、これらの ID を指定する場所を示しています。スプレッドシート ID はスプレッドシートの URL で確認できます。シート ID を取得するには、spreadsheets.get メソッドを使用します。範囲は A1 表記で指定します。範囲の例は「Sheet1!A1:D5」です。

また、プレースホルダ NAMED_RANGE_ID と PROTECTED_RANGE_ID は、名前付き範囲と保護されている範囲の ID を指定します。namedRangeId と protectedRangeId は、関連する範囲の更新または削除をリクエストするときに使用されます。この ID は、名前付き範囲または保護された範囲を作成する Sheets API リクエストのレスポンスで返されます。既存の範囲の ID は、Spreadsheet レスポンス本文の spreadsheets.get メソッドを使用して取得できます。

名前付き範囲または保護されている範囲を追加する

次の spreadsheets.batchUpdate コードサンプルは、2 つのリクエスト オブジェクトを使用する方法を示しています。1 つ目の方法は、AddNamedRangeRequest を使用して範囲 A1:E3 に「Counts」という名前を割り当てます。2 つ目の方法は、AddProtectedRangeRequest を使用して、範囲 A4:E4 に警告レベルの保護を適用します。このレベルの保護では、範囲内のセルの編集は可能ですが、変更を行う前に警告が表示されます。

これらのリクエストは、範囲 ID とプロパティを含む AddNamedRangeResponse と AddProtectedRangeResponse を返します。

リクエスト プロトコルを以下に示します。

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

{
  "requests": [
    {
      "addNamedRange": {
        "namedRange": {
          "name": "Counts",
          "range": {
            "sheetId": SHEET_ID,
            "startRowIndex": 0,
            "endRowIndex": 3,
            "startColumnIndex": 0,
            "endColumnIndex": 5,
          },
        }
      }
    },
    {
      "addProtectedRange": {
        "protectedRange": {
          "range": {
            "sheetId": SHEET_ID,
            "startRowIndex": 3,
            "endRowIndex": 4,
            "startColumnIndex": 0,
            "endColumnIndex": 5,
          },
          "description": "Protecting total row",
          "warningOnly": true
        }
      }
    }
  ]
}

名前付き範囲または保護されている範囲を削除する

次の spreadsheets.batchUpdate コードサンプルは、2 つのリクエスト オブジェクトを使用する方法を示しています。1 つ目の方法は、DeleteNamedRangeRequest と以前の API 呼び出しの NAMED_RANGE_ID を使用して、既存の名前付き範囲を削除します。2 つ目の方法は、DeleteProtectedRangeRequest と以前の API 呼び出しの PROTECTED_RANGE_ID を使用して、既存の範囲保護を削除します。

リクエスト プロトコルを以下に示します。

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

{
  "requests": [
    {
      "deleteNamedRange": {
          "namedRangeId": "NAMED_RANGE_ID",
      }
    },
    {
      "deleteProtectedRange": {
        "protectedRangeId": PROTECTED_RANGE_ID,
      }
    }
  ]
}

名前付き範囲または保護されている範囲を更新する

次の spreadsheets.batchUpdate コードサンプルは、2 つのリクエスト オブジェクトを使用する方法を示しています。1 つ目の方法は、UpdateNamedRangeRequest で既存の名前付き範囲の名前を「InitialCounts」に更新します。前の API 呼び出しの NAMED_RANGE_ID を使用します。2 つ目の方法は、UpdateProtectedRangeRequest を使用して既存の保護されている範囲を更新し、同じ名前付き範囲を保護するようにします。Editors メソッドを使用すると、リストされたユーザーのみがこれらのセルを編集できます。このリクエストでは、以前の API 呼び出しの NAMED_RANGE_ID と PROTECTED_RANGE_ID を使用します。

リクエスト プロトコルを以下に示します。

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

{
  "requests": [
    {
      "updateNamedRange": {
        "namedRange": {
          "namedRangeId": NAMED_RANGE_ID,
          "name": "InitialCounts",
        },
        "fields": "name",
      }
    },
    {
      "updateProtectedRange": {
        "protectedRange": {
          "protectedRangeId": PROTECTED_RANGE_ID,
          "namedRangeId": NAMED_RANGE_ID,
          "warningOnly": false,
          "editors": {
            "users": [
              "[e-mail]",
              "[e-mail]"
            ]
          }
        },
        "fields": "namedRangeId,warningOnly,editors"
      }
    }
  ]
}