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

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

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

デベロッパー メタデータを使用すると、次のようなオペレーションを実行できます。

  • 任意のデータをスプレッドシート内のさまざまなエンティティや場所に関連付ける - たとえば、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 を列に置き換えます。

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

プロジェクトとドキュメントに表示されるメタデータ

1 つのデベロッパー プロジェクトが別のプロジェクトのメタデータを干渉しないようにするには、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"
        }
      }
    }
  ]
}

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

1 つの個別のデベロッパー メタデータを取得するには、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 つ以上のデータフィルタを指定する必要があります。

このリクエストは、指定されたデータフィルタに一致するメタデータのリストによって、メタデータを含むシート、グリッドデータ、その他のオブジェクト リソースが返される点を除き、通常の「スプレッドシート 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 オブジェクトのキーと値の属性の各文字がこの上限にカウントされます。