Google SpreadsheetのGASでaddDeveloperMetadata関数を使ってみよう

Google Spreadsheetは、オンラインで簡単にスプレッドシートを作成・編集・共有できる便利なツールです。しかし、スプレッドシートには見えない情報もあります。それが開発者メタデータです。開発者メタデータとは、スプレッドシートやシート、セルなどのオブジェクトに紐づけられたキーと値のペアのことです。開発者メタデータを使うと、スプレッドシートのデータを検索したり、フィルターしたり、ソートしたりすることができます。また、開発者メタデータはユーザーには見えないので、スプレッドシートの見た目を変えることなく、裏側でデータを管理することができます。

では、開発者メタデータをどうやって設定するのでしょうか？そのときに使うのが、Google Apps Script（以下、GAS）のaddDeveloperMetadata関数です。この関数は、スプレッドシートに開発者メタデータを追加するための関数です。この記事では、この関数の使い方を解説します。

addDeveloperMetadata関数とは

addDeveloperMetadata関数は、スプレッドシートに開発者メタデータを追加するための関数です。この関数は、以下のように書きます。

Spreadsheet.addDeveloperMetadata(key, value, visibility)

この関数には、以下の3つの引数があります。

• key: 開発者メタデータのキーを指定する文字列です。キーは、開発者メタデータを識別するためのラベルのようなものです。
• value: 開発者メタデータの値を指定する文字列です。値は、キーに対応するデータです。
• visibility: 開発者メタデータの可視性を指定するDeveloperMetadataVisibility型の値です。可視性とは、開発者メタデータが誰に見えるかを決めるものです。可視性には、以下の2つの値があります。
  • DeveloperMetadataVisibility.DOCUMENT: 開発者メタデータがドキュメント全体で共有されることを示します。この場合、開発者メタデータは、スプレッドシートのすべてのユーザーに見えます。
  • DeveloperMetadataVisibility.PROJECT: 開発者メタデータがプロジェクト内でのみ共有されることを示します。この場合、開発者メタデータは、スプレッドシートの所有者と編集者にのみ見えます。

この関数を使うときは、keyとvalueは必ず指定する必要があります。visibilityは省略可能です。省略した場合は、DeveloperMetadataVisibility.PROJECTがデフォルト値として使われます。

addDeveloperMetadata関数のプログラムサンプルと実行結果

では、実際にaddDeveloperMetadata関数を使ってみましょう。以下のプログラムは、スプレッドシートに「name」というキーと「Alice」という値の開発者メタデータを追加するものです。

function addDeveloperMetadataExample() {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  spreadsheet.addDeveloperMetadata('name', 'Alice');
}

このプログラムを実行すると、スプレッドシートに開発者メタデータが追加されます。しかし、開発者メタデータはユーザーには見えないので、スプレッドシートの見た目には変化はありません。開発者メタデータを確認するには、スプレッドシートのメニューから「ツール」→「スクリプト エディター」を選択して、GASのコンソールを開きます。コンソールには、以下のようなメッセージが表示されます。

[20-01-24 10:38:42:042 JST] Developer metadata added to Spreadsheet with ID 1a2b3c4d5e6f7g8h9i0j: {key=name, value=Alice, visibility=PROJECT}

これは、スプレッドシートに開発者メタデータが追加されたことを示しています。また、キー、値、可視性の情報も表示されています。この例では、可視性は省略したので、デフォルト値のPROJECTになっています。

addDeveloperMetadata関数の戻り値とその活用方法

addDeveloperMetadata関数は、開発者メタデータを追加するだけでなく、追加した開発者メタデータを表すDeveloperMetadata型のオブジェクトを戻り値として返します。このオブジェクトを使うと、開発者メタデータの詳細な情報を取得したり、開発者メタデータを更新したり、削除したりすることができます。

例えば、以下のプログラムは、addDeveloperMetadata関数の戻り値を変数に代入して、その情報をコンソールに出力するものです。

function addDeveloperMetadataExample() {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  var developerMetadata = spreadsheet.addDeveloperMetadata('name', 'Alice');
  console.log('ID: ' + developerMetadata.getId());
  console.log('Key: ' + developerMetadata.getKey());
  console.log('Value: ' + developerMetadata.getValue());
  console.log('Visibility: ' + developerMetadata.getVisibility());
  console.log('Location type: ' + developerMetadata.getLocationType());
}

このプログラムを実行すると、コンソールには以下のようなメッセージが表示されます。

[20-01-24 10:38:42:042 JST] Developer metadata added to Spreadsheet with ID 1a2b3c4d5e6f7g8h9i0j: {key=name, value=Alice, visibility=PROJECT}
[20-01-24 10:38:42:043 JST] ID: 123456789
[20-01-24 10:38:42:044 JST] Key: name
[20-01-24 10:38:42:044 JST] Value: Alice
[20-01-24 10:38:42:045 JST] Visibility: PROJECT
[20-01-24 10:38:42:046 JST] Location type: SPREADSHEET

これは、開発者メタデータのID、キー、値、可視性、位置タイプの情報を示しています。位置タイプとは、開発者メタデータがどのオブジェクトに紐づけられているかを示すものです。この例では、スプレッドシート全体に開発者メタデータが追加されたので、位置タイプはSPREADSHEETになっています。

開発者メタデータのオブジェクトには、他にも以下のようなメソッドがあります。

• remove(): 開発者メタデータを削除するメソッドです
• setKey(key): 開発者メタデータのキーを変更するメソッドです。引数に新しいキーを指定します
• setValue(value): 開発者メタデータの値を変更するメソッドです。引数に新しい値を指定します
• setVisibility(visibility): 開発者メタデータの可視性を変更するメソッドです。引数に新しい可視性を指定します

これらのメソッドを使うと、開発者メタデータを柔軟に操作することができます。

まとめ

この記事では、GASのaddDeveloperMetadata関数について解説しました。この関数は、スプレッドシートに開発者メタデータを追加するための関数です。

開発者メタデータを使うと、スプレッドシートのデータを検索したり、フィルターしたり、ソートしたりすることができます。また、開発者メタデータはユーザーには見えないので、スプレッドシートの見た目を変えることなく、裏側でデータを管理することができます。

addDeveloperMetadata関数は、開発者メタデータを追加するだけでなく、追加した開発者メタデータを表すオブジェクトを戻り値として返します。このオブジェクトを使うと、開発者メタデータの詳細な情報を取得したり、開発者メタデータを更新したり、削除したりすることができます。

開発者メタデータは、スプレッドシートのデータを効率的に管理するための強力な機能です。ぜひ、addDeveloperMetadata関数を使って、スプレッドシートのデータをより便利に扱ってみてください。

参考文献

Spreadsheet | Apps Script | Google Developers

Class DeveloperMetadata | Apps Script | Google for Developers

Read & write developer metadata | Google Sheets | Google Developers