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

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

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

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

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