デベロッパー メタデータの読み取りと書き込み

デベロッパー メタデータ機能を使用すると、スプレッドシート内のさまざまなエンティティと場所にメタデータを関連付けることができます。このメタデータをクエリして、関連付けられているオブジェクトを見つけることができます。

メタデータを行、列、シート、またはスプレッドシートに関連付けることができます。

デベロッパー メタデータを使用して、次のような操作が可能です。

  • スプレッドシート内の任意のデータをさまざまなエンティティと場所に関連付ける - たとえば、totals を列 D に、responseId = 1234 を行 7 に関連付けます。

  • 特定のメタデータキーまたは属性に関連付けられているすべての場所とデータを検索する - たとえば、列 D に関連付けられているキー totals または responseId を指定して、responseId メタデータとそれに関連付けられているメタデータ値を含むすべての行を返します。

  • 特定のエンティティまたは場所に関連付けられているすべてのデータを検索する - たとえば、列 D の場合は、その場所に関連付けられているすべてのメタデータを返します。

  • 関連付けられているメタデータを指定して、場所の値を取得する - たとえば、totals が指定されている場合は、関連付けられている列または行に含まれる値の表現を返します。summary が指定されている場合は、関連付けられているシート リソースの表現を返します。

  • 関連付けられているメタデータを指定して、場所の値を更新する - たとえば、A1 表記で行の値を更新する代わりに、メタデータ ID を指定して値を更新します。

メタデータの読み取りと書き込み

spreadsheets.developerMetadata リソースを使用すると、スプレッドシート内の場所またはオブジェクトに関連付けられたデベロッパー メタデータにアクセスできます。

デベロッパー メタデータについて

このセクションでは、Sheets API を使用する際に考慮すべきデベロッパー メタデータの重要な要素について説明します。

タグとしてのメタデータ

デベロッパー メタデータの用途の一つは、キーと場所のみを使用してスプレッドシート内の場所に名前を付けるタグです。たとえば、headerRow を特定の行に関連付けたり、totals をシート内の特定の列に関連付けたりできます。タグを使用すると、スプレッドシートの一部をサードパーティ ツールまたはデータベースのフィールドに意味的にバインドできるため、スプレッドシートに加えられた変更がアプリに影響を及ぼすことはありません。

プロパティとしてのメタデータ

キー、場所、値を指定することにより作成されたメタデータは、シート内のその場所に関連付けられた Key-Value ペアとして機能します。たとえば、次のようなものを関連付けることができます。

  • formResponseId = resp123 と行
  • lastUpdated = 1477369882 を列に置き換えます。

これにより、スプレッドシートの特定の領域やデータに関連付けられている、カスタム名が付けられたプロパティを保存したり、そのプロパティにアクセスしたりできます。

プロジェクトとドキュメントの可視メタデータ

あるデベロッパー プロジェクトが別のプロジェクトのメタデータを干渉しないようにするために、project と document の 2 つのメタデータ visibility 設定があります。Sheets API を使用する場合、プロジェクト メタデータは、そのメタデータが作成されたデベロッパー プロジェクトのみからの可視性があり、そのプロジェクトからアクセスできます。ドキュメント メタデータには、ドキュメントへのアクセス権があるすべてのデベロッパー プロジェクトからアクセスできます。

可視性を明示的に指定しないクエリは、リクエスト作成元のデベロッパー プロジェクトの一致するドキュメント メタデータに加えて、一致するプロジェクト メタデータを返します。

一意性

メタデータキーは一意である必要はありませんが、metadataId は一意にする必要があります。メタデータを作成して、その ID フィールドを指定しないままにすると、API により ID が割り当てられます。この ID を使用してメタデータを識別したり、キーとその他の属性を使用してメタデータのセットを識別したりできます。

メタデータを作成する

メタデータを作成するには、batchUpdate メソッドを使用して、createDeveloperMetadataRequest に metadataKey、location、visibility を指定します。必要に応じて、metadataValue または明示的な metadataId を指定できます。

すでに使用されている ID を指定した場合、リクエストは失敗します。ID を指定しない場合、API によって ID が割り当てられます。

例を表示

この例では、リクエストにキー、値、行を指定します。レスポンスには、これらのデベロッパー メタデータ値と、割り当てられたメタデータ ID が返されます。

リクエスト

{
  "requests": [
    {
      "createDeveloperMetadata": {
        "developerMetadata": {
          "location": {
            "dimensionRange": {
              "sheetId": sheetId,
              "dimension": "ROWS",
              "startIndex": 6,
              "endIndex": 7
            }
          },
          "visibility": "DOCUMENT",
          "metadataKey": "Sales",
          "metadataValue": "2022"
        }
      }
    }
  ]
}

レスポンス

{
  "spreadsheetId": spreadsheetId,
  "replies": [
    {
      "createDeveloperMetadata": {
        "developerMetadata": {
          "metadataId": metadataId,
          "metadataKey": "Sales",
          "metadataValue": "2022",
          "location": {
            "locationType": "ROW",
            "dimensionRange": {
              "sheetId": sheetId,
              "dimension": "ROWS",
              "startIndex": 6,
              "endIndex": 7
            }
          },
          "visibility": "DOCUMENT"
        }
      }
    }
  ]
}

単一のメタデータ アイテムを読み取る

単一の個別のデベロッパー メタデータを取得するには、spreadsheets.developerMetadata.get メソッドを使用して、メタデータを含む spreadsheetId とデベロッパー メタデータの一意の metadataId を指定します。

例を表示

リクエスト

この例では、リクエストでスプレッドシート ID とメタデータ ID を指定します。レスポンスには、メタデータ ID のデベロッパー メタデータ値が返されます。

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId

レスポンス

{
  "metadataId": metadataId,
  "metadataKey": "Sales",
  "metadataValue": "2022",
  "location": {
    "locationType": "ROW",
    "dimensionRange": {
      "sheetId": sheetId,
      "dimension": "ROWS",
      "startIndex": 6,
      "endIndex": 7
    }
  },
  "visibility": "DOCUMENT"
}

複数のメタデータ アイテムを読み取る

デベロッパー メタデータの複数のアイテムを取得するには、spreadsheets.developerMetadata.search メソッドを使用します。キー、値、場所、可視性などのプロパティの組み合わせに関する既存のメタデータに一致する DataFilter を指定する必要があります。

例を表示

この例では、リクエストで複数のメタデータ ID を指定します。レスポンスには、各メタデータ ID のデベロッパー メタデータ値が返されます。

リクエスト

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    },
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ]
}

レスポンス

{
  "matchedDeveloperMetadata": [
    {
      "developerMetadata": {
        "metadataId": metadataId,
        "metadataKey": "Revenue",
        "metadataValue": "2022",
        "location": {
          "locationType": "SHEET",
          "sheetId": sheetId
        },
        "visibility": "DOCUMENT"
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      ]
    },
    {
      "developerMetadata": {
        "metadataId": metadataId,
        "metadataKey": "Sales",
        "metadataValue": "2022",
        "location": {
          "locationType": "SHEET",
          "sheetId": sheetId
        },
        "visibility": "DOCUMENT"
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      ]
    }
  ]
}

メタデータを更新

デベロッパー メタデータを更新するには、spreadsheets.batchUpdate メソッドを使用して UpdateDeveloperMetadataRequest を指定します。更新するメタデータを対象とする DataFilter、新しい値を含む DeveloperMetadata オブジェクト、更新するフィールドを記述するフィールドマスクを指定する必要があります。

例を表示

この例では、リクエストにメタデータ ID、シート ID、新しいメタデータキーを指定します。レスポンスには、これらのデベロッパー メタデータ値と、更新されたメタデータキーが返されます。

リクエスト

{
  "requests": [
    {
      "updateDeveloperMetadata": {
        "dataFilters": [
          {
            "developerMetadataLookup": {
              "metadataId": metadataId
            }
          }
        ],
        "developerMetadata": {
          "location": {
            "sheetId": sheetId
          },
          "metadataKey": "SalesUpdated"
        },
        "fields": "location,metadataKey"
      }
    }
  ]
}

レスポンス

{
  "spreadsheetId": spreadsheetId,
  "replies": [
    {
      "updateDeveloperMetadata": {
        "developerMetadata": [
          {
            "metadataId": metadataId,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": sheetId
            },
            "visibility": "DOCUMENT"
          }
        ]
      }
    }
  ]
}

メタデータを削除する

デベロッパー メタデータを削除するには、batchUpdate メソッドを使用して、DeleteDeveloperMetadataRequest を指定します。削除するメタデータを選択するために、DataFilter を指定する必要があります。

例を表示

この例では、リクエストでメタデータ ID を指定します。レスポンスには、メタデータ ID のデベロッパー メタデータ値が返されます。

デベロッパー メタデータが削除されたことを確認するには、削除されたメタデータ ID を指定して spreadsheets.developerMetadata.get メソッドを使用します。404: Not Found HTTP ステータス コード レスポンスが返され、メッセージ「ID metadataId のデベロッパー メタデータはありません」が表示されます。

リクエスト

{
  "requests": [
    {
      "deleteDeveloperMetadata": {
        "dataFilter": {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      }
    }
  ]
}

レスポンス

{
  "spreadsheetId": spreadsheetId,
  "replies": [
    {
      "deleteDeveloperMetadata": {
        "deletedDeveloperMetadata": [
          {
            "metadataId": metadataId,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": sheetId
            },
            "visibility": "DOCUMENT"
          }
        ]
      }
    }
  ]
}

メタデータに関連付けられている値の読み取りと書き込み

関連するデベロッパー メタデータと更新する値を指定して、行と列のセル値を取得して更新することもできます。取得するには、一致する DataFilter を指定して、以下の適切なメソッドを使用します。

メタデータでセル値を取得する

メタデータを使用してセル値を取得するには、spreadsheets.values.batchGetByDataFilter メソッドを使用します。スプレッドシート ID と、メタデータに一致する 1 つ以上のデータフィルタを指定する必要があります。

例を表示

この例では、リクエストでメタデータ ID を指定します。レスポンスには、メタデータ ID の行セル値（モデル番号、月間販売数）が返されます。

リクエスト

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ],
  "majorDimension": "ROWS"
}

レスポンス

{
  "spreadsheetId": spreadsheetId,
  "valueRanges": [
    {
      "valueRange": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "74"
          ]
        ]
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      ]
    }
  ]
}

メタデータでスプレッドシートを取得する

スプレッドシートを取得するときに、spreadsheets.getByDataFilter メソッドを使用してデータのサブセットを返すことができます。スプレッドシート ID と、メタデータに一致する 1 つ以上のデータフィルタを指定する必要があります。

このリクエストは、指定したデータフィルタに一致するメタデータのリストにより、返されるシート、グリッドデータ、およびメタデータに関連付けられている他のオブジェクト リソースが決定されることを除いて、通常の「spreadsheet GET」リクエストとして機能します。includeGridData が true に設定されている場合は、シートの指定したグリッド範囲を横断するグリッドデータも返されます。

例を表示

この例では、メタデータ ID を指定し、リクエストで includeGridData を false に設定します。レスポンスには、スプレッドシートとシートのプロパティの両方が返されます。

リクエスト

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ],
  "includeGridData": false
}

レスポンス

{
  "spreadsheetId": spreadsheetId,
  "properties": {
    "title": "Sales Sheet",
    "locale": "en_US",
    "autoRecalc": "ON_CHANGE",
    "timeZone": "America/Los_Angeles",
    "defaultFormat": {
      "backgroundColor": {
        "red": 1,
        "green": 1,
        "blue": 1
      },
      "padding": {
        "top": 2,
        "right": 3,
        "bottom": 2,
        "left": 3
      },
      "verticalAlignment": "BOTTOM",
      "wrapStrategy": "OVERFLOW_CELL",
      "textFormat": {
        "foregroundColor": {},
        "fontFamily": "arial,sans,sans-serif",
        "fontSize": 10,
        "bold": false,
        "italic": false,
        "strikethrough": false,
        "underline": false,
        "foregroundColorStyle": {
          "rgbColor": {}
        }
      },
      "backgroundColorStyle": {
        "rgbColor": {
          "red": 1,
          "green": 1,
          "blue": 1
        }
      }
    },
    "spreadsheetTheme": {
      "primaryFontFamily": "Arial",
      "themeColors": [
        {
          "colorType": "TEXT",
          "color": {
            "rgbColor": {}
          }
        },
        {
          "colorType": "BACKGROUND",
          "color": {
            "rgbColor": {
              "red": 1,
              "green": 1,
              "blue": 1
            }
          }
        },
        {
          "colorType": "ACCENT1",
          "color": {
            "rgbColor": {
              "red": 0.25882354,
              "green": 0.52156866,
              "blue": 0.95686275
            }
          }
        },
        {
          "colorType": "ACCENT2",
          "color": {
            "rgbColor": {
              "red": 0.91764706,
              "green": 0.2627451,
              "blue": 0.20784314
            }
          }
        },
        {
          "colorType": "ACCENT3",
          "color": {
            "rgbColor": {
              "red": 0.9843137,
              "green": 0.7372549,
              "blue": 0.015686275
            }
          }
        },
        {
          "colorType": "ACCENT4",
          "color": {
            "rgbColor": {
              "red": 0.20392157,
              "green": 0.65882355,
              "blue": 0.3254902
            }
          }
        },
        {
          "colorType": "ACCENT5",
          "color": {
            "rgbColor": {
              "red": 1,
              "green": 0.42745098,
              "blue": 0.003921569
            }
          }
        },
        {
          "colorType": "ACCENT6",
          "color": {
            "rgbColor": {
              "red": 0.27450982,
              "green": 0.7411765,
              "blue": 0.7764706
            }
          }
        },
        {
          "colorType": "LINK",
          "color": {
            "rgbColor": {
              "red": 0.06666667,
              "green": 0.33333334,
              "blue": 0.8
            }
          }
        }
      ]
    }
  },
  "sheets": [
    {
      "properties": {
        "sheetId": sheetId,
        "title": "Sheet7",
        "index": 7,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 1000,
          "columnCount": 26
        }
      }
    }
  ],
  "spreadsheetUrl": spreadsheetUrl
}

メタデータで値を更新する

特定のメタデータに一致するセル値を更新するには、spreadsheets.values.batchUpdateByDataFilter メソッドを使用します。スプレッドシート ID valueInputOption と、メタデータに一致する 1 つ以上の DataFilterValueRange を指定する必要があります。

例を表示

この例では、リクエストでメタデータ ID と更新された行の値を指定します。レスポンスには、更新されたプロパティとメタデータ ID のデータの両方が返されます。

リクエスト

{
  "data": [
    {
      "dataFilter": {
        "developerMetadataLookup": {
          "metadataId": metadataId
        }
      },
      "majorDimension": "ROWS",
      "values": [
        [
          "W-24",
          "84"
        ]
      ]
    }
  ],
  "includeValuesInResponse": true,
  "valueInputOption": "USER_ENTERED"
}

レスポンス

{
  "spreadsheetId": spreadsheetId,
  "totalUpdatedRows": 1,
  "totalUpdatedColumns": 2,
  "totalUpdatedCells": 2,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "updatedRange": "Sheet7!A7:B7",
      "updatedRows": 1,
      "updatedColumns": 2,
      "updatedCells": 2,
      "dataFilter": {
        "developerMetadataLookup": {
          "metadataId": metadataId
        }
      },
      "updatedData": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "84"
          ]
        ]
      }
    }
  ]
}

メタデータで値を消去する

特定のメタデータに一致するセル値を消去するには、spreadsheets.values.batchClearByDataFilter メソッドを使用します。消去するメタデータを選択するために、データフィルタを指定する必要があります。

例を表示

リクエスト

この例では、リクエストでメタデータ ID を指定します。レスポンスには、スプレッドシート ID と消去された範囲が返されます。

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ]
}

レスポンス

{
  "spreadsheetId": spreadsheetId,
  "clearedRanges": [
    "Sheet7!A7:Z7"
  ]
}

メタデータ ストレージの上限

スプレッドシートに格納できるメタデータの合計量には上限があります。この上限は文字数で計算され、次の 2 つのコンポーネントで構成されます。

項目 保存容量の上限の割り当て
スプレッドシート 30,000 文字
スプレッドシート内の各シート 30,000 文字

スプレッドシートには最大で 30,000 文字格納できます。また、スプレッドシート内の各シートに 30,000 文字を格納できます（シート 1 に 30,000 文字、シート 2 に 30,000 文字など）。したがって、3 つのページがあるスプレッドシートには最大 120,000 文字のデベロッパー メタデータが格納できます。

developerMetadata オブジェクトの key 属性と value 属性の各文字がこの上限に対してカウントされます。