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

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

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

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

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