カスタム ファイルのプロパティを追加する

カスタム ファイル プロパティは、Google ドライブ ファイルのカスタム メタデータ（タグなど）、他のデータストアの ID、ワークフロー アプリケーション間で共有される情報などを保存するために使用される Key-Value ペアです。たとえば、第 1 四半期に営業部門が作成したすべてのドキュメントにファイル プロパティを追加できます。

すべてのアプリケーションに表示されるプロパティを追加するには、files リソースの properties フィールドを使用します。アプリに制限されたプロパティを追加するには、files リソースの appProperties フィールドを使用します。

プロパティは検索式でも使用できます。

これは、ファイルにドライブ ファイルのデータベース ID を保存するために使用される一般的なプロパティの構造です。

Drive API v3

"appProperties": {
  "additionalID": "ID",
}

Drive API v2

{
  'key':        'additionalID',
  'value':      'ID',
  'visibility': 'PRIVATE'
}

カスタム ファイルのプロパティの操作

このセクションでは、すべてのアプリケーションに影響するカスタム ファイル プロパティ関連のタスクを実行する方法について説明します。

カスタム ファイルのプロパティを追加または更新する

すべてのアプリケーションに表示されるプロパティを追加または更新するには、files.update メソッドを使用して、files リソースの properties フィールドを設定します。

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
 
{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

Google Apps Script の高度なドライブ サービスを使用して、ファイルにカスタム プロパティを追加することもできます。詳細については、カスタム プロパティの追加をご覧ください。

カスタム ファイルのプロパティを取得または一覧表示する

すべてのアプリケーションに表示されるプロパティを表示するには、files.get メソッドを使用して、ファイルのカスタム ファイル プロパティを取得します。

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=properties

レスポンスは、Key-Value ペアのコレクションを含む properties オブジェクトで構成されます。

{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

カスタム ファイルのプロパティを削除する

すべてのアプリケーションに表示されるプロパティ値を削除するには、files.update メソッドを使用して、files リソースの properties フィールドを null に設定します。

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
 
{
  "name": null
}

変更を表示するには、files.get メソッドを呼び出して、ファイルの properties オブジェクトを取得します。

{
  "properties": {
    "mass": "1.3kg",
    "count": "3"
  }
}

カスタム ファイル プロパティの制限事項

カスタム プロパティには次の制限があります。

  • ファイルあたりのカスタム プロパティの最大数は 100 個です（すべてのソースの合計）。
  • ファイルあたりの公開プロパティの最大数は 30 個です。これはすべてのソースの合計です。
  • 1 つのアプリケーションから 1 つのファイルに設定できる非公開プロパティの最大数は 30 個です。
  • UTF-8 エンコードで、プロパティ文字列（キーと値の両方を含む）あたり最大 124 バイト。たとえば、キーが 10 文字のプロパティの場合、値には 114 文字しか含めることができません。同様に、値に 100 文字が必要なプロパティでは、キーに最大 24 文字を使用できます。

詳細については、files リソースをご覧ください。Drive API v2 については、properties リソースをご覧ください。

非公開のカスタム ファイル プロパティにアクセスする

限定公開プロパティを取得できるのは、OAuth 2.0 クライアント ID で取得したアクセス トークンを使用する認証済みリクエストで appProperties フィールドを使用する場合のみです。API キーを使用して非公開プロパティを取得することはできません。