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

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

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

デベロッパー メタデータを使用すると、次のような操作を実行できます。

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

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

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

  • 関連するメタデータを指定してロケーションの値を取得する - たとえば、totals が関連する列または行に含まれる値の表現を返す場合、または summary が関連するスプレッドシート リソースの表現を返す場合。

  • 関連するメタデータを指定してビジネスの値を更新する - たとえば、行の値を A1 表記で更新するのではなく、メタデータ ID を指定して値を更新します。

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

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

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

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

タグとしてのメタデータ

デベロッパー メタデータの用途の 1 つに、キーと場所のみを使用してスプレッドシート内の場所に名前を付けるタグがあります。たとえば、headerRow を特定の行に関連付けることも、totals をシート内の特定の列に関連付けることもできます。タグを使用すると、スプレッドシートの一部をサードパーティのツールやデータベースのフィールドにセマンティックにバインドできるため、スプレッドシートを変更してもアプリに不具合が生じることはありません。

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

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

  • 行がある formResponseId = resp123
  • lastUpdated = 1477369882 は列に置き換えます。

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

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

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

公開設定を明示的に指定していないクエリは、リクエストを行うデベロッパー プロジェクトの一致するドキュメント メタデータとプロジェクト メタデータを返します。

一意性

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

メタデータを作成する

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

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

例を表示

この例では、リクエストのキー、値、行を指定します。レスポンスでは、これらのデベロッパー メタデータの値と、割り当てられたメタデータ 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 メソッドを使用して、メタデータとデベロッパー メタデータの一意の metadataId を含む spreadsheetId を指定します。

例を表示

リクエスト

この例では、リクエストでスプレッドシート 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 のデベロッパー メタデータ値を返します。

デベロッパー メタデータが削除されたことを確認するには、spreadsheets.developerMetadata.get メソッドを使用して、削除されたメタデータ ID を指定します。「No developer metadata with ID metadataId」というメッセージとともに、404: Not FoundHTTP ステータス コード レスポンスが返されます。

リクエスト

{
  "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 オブジェクトのキーと値の属性の各文字が、この上限に対してカウントされます。