Googleスプレッドシートのメタデータを検索する方法 | createDeveloperMetadataFinder関数

Googleスプレッドシートは、オンラインで表計算を行う便利なツールです。しかし、時にはスプレッドシートのセルやシートに、見えないデータを付与したいときもあります。例えば、セルの値に対して、コメントやタグやキーなどを追加したり、シートに対して、カテゴリや属性などを設定したりするときなどです。

Googleスプレッドシートには、このような見えないデータを付与するための機能として、開発者メタデータというものがあります。開発者メタデータとは、スプレッドシートのセルやシートに、キーと値のペアでデータを保存できる機能です。開発者メタデータは、Google Apps Script（GAS）を使って、追加や削除や取得や検索などができます。

GASのcreateDeveloperMetadataFinder関数の使い方

GASのcreateDeveloperMetadataFinder関数は、スプレッドシートのメタデータを検索する関数です。createDeveloperMetadataFinder関数は、Spreadsheetクラスのメソッドとして定義されています。Spreadsheetクラスは、スプレッドシートを表すクラスです。createDeveloperMetadataFinder関数は、以下のように使います。

// スプレッドシートを取得
const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();

// メタデータの検索情報を作る
const finder = spreadsheet.createDeveloperMetadataFinder();

このコードでは、アクティブなスプレッドシートを取得して、そのメタデータの検索情報を作っています。createDeveloperMetadataFinder関数は、引数を受け取りません。createDeveloperMetadataFinder関数は、メタデータの検索情報を表すDeveloperMetadataFinderオブジェクトを返します。このオブジェクトを使えば、メタデータの検索条件を指定したり、メタデータの検索結果を取得したりできます。

createDeveloperMetadataFinder関数の引数と戻り値の意味

createDeveloperMetadataFinder関数は、引数を受け取りません。戻り値は、メタデータの検索情報を表すDeveloperMetadataFinderオブジェクトです。DeveloperMetadataFinderオブジェクトは、以下のメソッドを持ちます。

• withKey(key)：キーでメタデータを検索する条件を追加します。keyは、メタデータのキーとなる文字列です。
• withValue(value)：値でメタデータを検索する条件を追加します。valueは、メタデータの値となる文字列です。
• withLocationType(locationType)：位置タイプでメタデータを検索する条件を追加します。locationTypeは、メタデータの位置タイプとなるDeveloperMetadataLocationType列挙型の値です。位置タイプとは、メタデータが付与された場所の種類で、以下の値があります。
  • SPREADSHEET：スプレッドシート全体に付与されたメタデータ
  • SHEET：シートに付与されたメタデータ
  • ROW：行に付与されたメタデータ
  • COLUMN：列に付与されたメタデータ
• withLocation(location)：位置でメタデータを検索する条件を追加します。locationは、メタデータの位置となるDeveloperMetadataLocationオブジェクトです。位置とは、メタデータが付与された場所の詳細で、位置タイプと対応するオブジェクトを指定します。
  • SPREADSHEET：Spreadsheetオブジェクト
  • SHEET：Sheetオブジェクト
  • ROW：Rangeオブジェクト
  • COLUMN：Rangeオブジェクト
• withVisibility(visibility)：可視性でメタデータを検索する条件を追加します。visibilityは、メタデータの可視性となるDeveloperMetadataVisibility列挙型の値です。可視性とは、メタデータが他のユーザーやアプリケーションに見えるかどうかの設定で、以下の値があります。
  • DOCUMENT：メタデータがスプレッドシートのドキュメントに紐づいており、他のユーザーやアプリケーションに見える
  • PROJECT：メタデータがGASのプロジェクトに紐づいており、同じプロジェクト内のスクリプトからのみ見える
• find()：メタデータの検索を実行し、検索結果を返します。検索結果は、メタデータを表すDeveloperMetadataオブジェクトの配列です。

これらのメソッドは、チェーンでつなげて使うことができます。例えば、以下のコードでは、キーと値と位置タイプと可視性でメタデータを検索する条件を指定して、検索を実行しています。

// スプレッドシートを取得
const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();

// メタデータの検索情報を作る
const finder = spreadsheet.createDeveloperMetadataFinder();

// メタデータの検索条件を指定
finder.withKey("メタデータ1")
      .withValue("値A")
      .withLocationType(SpreadsheetApp.DeveloperMetadataLocationType.ROW)
      .withVisibility(SpreadsheetApp.DeveloperMetadataVisibility.PROJECT);

// メタデータの検索を実行
const results = finder.find();

このコードでは、キーが「メタデータ1」、値が「値A」、位置タイプが「ROW」、可視性が「PROJECT」となるメタデータを検索しています。検索結果は、resultsという変数に格納されます。検索結果は、メタデータを表すDeveloperMetadataオブジェクトの配列です。DeveloperMetadataオブジェクトは、以下のメソッドを持ちます。

• getKey()：メタデータのキーを返します。
• getValue()：メタデータの値を返します。
• getLocation()：メタデータの位置を返します。
• getLocationType()：メタデータの位置タイプを返します。
• getVisibility()：メタデータの可視性を返します。
• getId()：メタデータのIDを返します。
• remove()：メタデータを削除します。

これらのメソッドを使えば、検索したメタデータの情報を取得したり、削除したりできます。

記事の続きを書いてくださいというリクエストにお応えします。以下のマークダウン形式の記事を参考にしてください。

createDeveloperMetadataFinder関数の活用例

createDeveloperMetadataFinder関数を使えば、スプレッドシートのメタデータを検索することができますが、そのままではあまり便利ではありません。メタデータを検索するだけではなく、メタデータを利用してスプレッドシートを操作したり、分析したりすることが重要です。

そこで、createDeveloperMetadataFinder関数を他のGASの関数と組み合わせて、より便利に使う方法を紹介します。以下の例では、メタデータを検索して、そのメタデータが付与されたセルやシートの値を取得する方法を示します。

// スプレッドシートを取得
const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();

// メタデータの検索情報を作る
const finder = spreadsheet.createDeveloperMetadataFinder();

// メタデータの検索条件を指定
finder.withKey("メタデータ2")
      .withValue("値B")
      .withLocationType(SpreadsheetApp.DeveloperMetadataLocationType.COLUMN);

// メタデータの検索を実行
const results = finder.find();

// 検索結果をログに出力
Logger.log(results.length + "件のメタデータが見つかりました");

// 検索結果をループで処理
for (let i = 0; i < results.length; i++) {
  // メタデータを取得
  const metadata = results[i];

  // メタデータの位置を取得
  const location = metadata.getLocation();

  // メタデータの位置タイプを取得
  const locationType = metadata.getLocationType();

  // メタデータの位置タイプに応じて処理を分岐
  switch (locationType) {
    case SpreadsheetApp.DeveloperMetadataLocationType.SPREADSHEET:
      // スプレッドシート全体に付与されたメタデータの場合
      // スプレッドシートの名前を取得
      const spreadsheetName = location.getSpreadsheet().getName();

      // ログに出力
      Logger.log("スプレッドシート「" + spreadsheetName + "」にメタデータが付与されています");
      break;
    case SpreadsheetApp.DeveloperMetadataLocationType.SHEET:
      // シートに付与されたメタデータの場合
      // シートの名前を取得
      const sheetName = location.getSheet().getName();

      // ログに出力
      Logger.log("シート「" + sheetName + "」にメタデータが付与されています");
      break;
    case SpreadsheetApp.DeveloperMetadataLocationType.ROW:
      // 行に付与されたメタデータの場合
      // 行の範囲を取得
      const rowRange = location.getRow();

      // 行の値を取得
      const rowValues = rowRange.getValues();

      // ログに出力
      Logger.log("行「" + rowRange.getA1Notation() + "」にメタデータが付与されています");
      Logger.log("行の値は「" + rowValues + "」です");
      break;
    case SpreadsheetApp.DeveloperMetadataLocationType.COLUMN:
      // 列に付与されたメタデータの場合
      // 列の範囲を取得
      const columnRange = location.getColumn();

      // 列の値を取得
      const columnValues = columnRange.getValues();

      // ログに出力
      Logger.log("列「" + columnRange.getA1Notation() + "」にメタデータが付与されています");
      Logger.log("列の値は「" + columnValues + "」です");
      break;
  }
}

このコードでは、キーが「メタデータ2」、値が「値B」、位置タイプが「COLUMN」となるメタデータを検索しています。検索結果は、resultsという変数に格納されます。検索結果は、メタデータを表すDeveloperMetadataオブジェクトの配列です。

検索結果をループで処理して、メタデータの位置を取得します。メタデータの位置は、メタデータの位置タイプに応じて、スプレッドシートやシートや行や列を表すオブジェクトです。メタデータの位置タイプは、getLocationTypeメソッドで取得できます。メタデータの位置タイプに応じて、switch文で処理を分岐します。

メタデータの位置タイプが「SPREADSHEET」の場合は、スプレッドシート全体に付与されたメタデータです。スプレッドシートを表すSpreadsheetオブジェクトは、getLocationメソッドで取得できます。このオブジェクトから、スプレッドシートの名前をgetNameメソッドで取得して、ログに出力します。

メタデータの位置タイプが「SHEET」の場合は、シートに付与されたメタデータです。シートを表すSheetオブジェクトは、getLocationメソッドで取得できます。このオブジェクトから、シートの名前をgetNameメソッドで取得して、ログに出力します。

メタデータの位置タイプが「ROW」の場合は、行に付与されたメタデータです。行を表すRangeオブジェクトは、getLocationメソッドで取得できます。このオブジェクトから、行の範囲をgetA1Notationメソッドで取得して、ログに出力します。また、行の値をgetValuesメソッドで取得して、ログに出力します。

メタデータの位置タイプが「COLUMN」の場合は、列に付与されたメタデータです。列を表すRangeオブジェクトは、getLocationメソッドで取得できます。このオブジェクトから、列の範囲をgetA1Notationメソッドで取得して、ログに出力します。また、列の値をgetValuesメソッドで取得して、ログに出力します。

このコードを実行すると、メタデータが付与されたセルやシートの値をログに表示できます。このように、メタデータを検索して、そのメタデータが付与されたセルやシートの値を取得することで、スプレッドシートのデータを分析したり、加工したりすることができます。

まとめ

この記事では、GASのcreateDeveloperMetadataFinder関数を使って、スプレッドシートのメタデータを検索する方法を紹介しました。

createDeveloperMetadataFinder関数を他のGASの関数と組み合わせれば、メタデータを利用してスプレッドシートを操作したり、分析したりすることができます。例えば、メタデータを検索して、そのメタデータが付与されたセルやシートの値を取得することができます。

参考文献

https://developers.google.com/apps-script/reference/spreadsheet/spreadsheet?hl=ja#createdevelopermetadatafinder