メタデータフィルタ

ガイド 検索 メタデータフィルタ

メタデータフィルタ

GET /search APIでは、関連付けられたメタデータを使用して、検索結果にフィルタをかけることができます。mdfiltersクエリパラメータを使用すると、開発者はメタデータテンプレートとクエリの対象となる値を指定できます。

cURL
curl -i -X GET "https://api.box.com/2.0/search?query=sales&mdfilters=%5B%7B%22scope%22%3A%22enterprise%22%2C%22templateKey%22%3A%22contract%22%2C%22filters%22%3A%7B%22category%22%3A%22online%22%7D%7D%5D" \
     -H "Authorization: Bearer <ACCESS_TOKEN>"
Java
long offsetValue = 0;
long limitValue = 10;

BoxSearch boxSearch = new BoxSearch(api);
BoxSearchParameters searchParams = new BoxSearchParameters();
searchParams.setQuery("sales");

BoxMetadataFilter bmf = new BoxMetadataFilter();
bmf.setScope("enterprise");
bmf.setTemplateKey("contract");
bmf.setFilter("category", "online")
searchParams.setMetadataFilter(bmf)

PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);
.NET
var filter = new
{
  category = "online"
};

var filters = new List<BoxMetadataFilterRequest>()
{
    new BoxMetadataFilterRequest()
    {
        Scope = "enterprise",
        TemplateKey = "contract",
        Filters: filter
    }
};
BoxCollection<BoxItem> results = await client.SearchManager
    .QueryAsync("sales", mdFilters: filters);
Python
from boxsdk.object.search import MetadataSearchFilter, MetadataSearchFilters

metadata_search_filter = MetadataSearchFilter(scope='enterprise', template_key='contract')
metadata_search_filter.add_value_based_filter(field_key='category', value='online')
metadata_search_filters = MetadataSearchFilters()
metadata_search_filters.add_filter(metadata_search_filter)

client.search().query("sales", metadata_filters=metadata_search_filters)
Node
client.search.query(
  'sales',
  {
    mdfilters: [
      {
        scope: 'enterprise',
        templateKey: 'contract',
        filters: {
          category: 'online;
        }
      }
    ]
  })
  .then(results => {
    // ...
  });

この例では、enterprise.contractメタデータが追加され、categoryフィールドがonlineに設定されている項目によって、クエリsalesに一致するコンテンツの検索にフィルタをかけます。

メタデータの概要

メタデータを使用すると、ユーザーやアプリケーションは、ファイルやフォルダに関連付けられたカスタムデータを定義、格納できます。

文字列フィールド

メタデータは、ファイルまたはフォルダに割り当てられているキー/値ペアで構成されます。たとえば、重要な契約には、clientNumber: 820183category: onlineのキー/値ペアが使用されている場合があります。

mdfiltersクエリパラメータを使用すると、開発者は、特定のメタデータが追加されているファイルとフォルダを検索できます。

メタデータテンプレートおよびインスタンスの詳細を確認する

メタデータフィルタ構文

mdfiltersパラメータに現在指定できるフィルタは1つだけですが、今後拡張される可能性があります。

各フィルタでは、フィルタをかけるメタデータテンプレートのscopeおよびtemplateKeyを定義します。

[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {}
  }
]

テンプレートのscopetemplateKeyを取得するには、会社のすべてのメタデータテンプレートのリストを取得するか、項目のすべてのメタデータインスタンスのリストを取得します。

テンプレートが定義されると、filtersフィールドではいくつかの異なるフィルタ形式が受け入れられます。フィルタの形式は、フィルタとして使用するフィールドのタイプによって大きく異なります。

stringフィールドによるフィルタ

stringタイプのフィールドでフィルタをかけるには、フィルタでフィールドのkeyと、項目を検索する際に目的となる値を定義する必要があります。

[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "category": "online"
    }
  }
]

この例では、enterprise.contractテンプレートのインスタンスが適用されていて、キーcategoryのフィールドが値onlineに設定されているすべてのファイルとフォルダが検索されます。

floatフィールドによるフィルタ

floatタイプのフィールドでフィルタをかけるには、フィルタでフィールドのkeyと、項目を検索する際に目的となる値を定義する必要があります。

[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "amount": 10000
    }
  }
]

この例では、enterprise.contractテンプレートのインスタンスが適用されていて、キーamountのフィールドが値10000に設定されているすべてのファイルとフォルダが検索されます。

さらに、floatフィールドのフィルタでは、直接的な値ではなく、gt (より大きい) やlt (より小さい) の値を指定して範囲を定義できます。

[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "amount": {
        "gt": 10000,
        "lt": 20000
      }
    }
  }
]

この例では、enterprise.contractテンプレートのインスタンスが適用されていて、キーamountのフィールドが10000以上2000以下の値に設定されているすべてのファイルおよびフォルダが検索されます。gtltはその値を含むことと、両方を設定する必要がないことに注意してください。

dateフィールドによるフィルタ

dateタイプのフィールドでフィルタをかけるには、フィルタでフィールドのkeyと、項目を検索する際に目的となる値を定義する必要があります。

[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "expirationDate": "2016-08-01T00:00:00Z"
    }
  }
]

この例では、enterprise.contractテンプレートのインスタンスが適用されていて、キーexpirationDateのフィールドが値2016-08-01T00:00:00Zに設定されているすべてのファイルとフォルダが検索されます。

さらに、dateフィールドのフィルタでは、直接的な値ではなく、gt (より大きい) やlt (より小さい) の値を指定して範囲を定義できます。

[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "expirationDate": {
        "gt": "2016-08-01T00:00:00Z",
        "lt": "2017-08-01T00:00:00Z"
      }
    }
  }
]

この例では、enterprise.contractテンプレートのインスタンスが適用されていて、キーexpirationDateのフィールドが2016-08-01T00:00:00Z以降2017-08-01T00:00:00Z以前の値に設定されているすべてのファイルおよびフォルダが検索されます。gtltはその値を含むことと、両方を設定する必要がないことに注意してください。

enumフィールドによるフィルタ

enumタイプのフィールドでフィルタをかけるには、フィルタでフィールドのkeyと、項目を検索する際に目的となる値を定義する必要があります。

[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "category": "online"
    }
  }
]

この例では、enterprise.contractテンプレートのインスタンスが適用されていて、キーcategoryのフィールドが値onlineに設定されているすべてのファイルとフォルダが検索されます。

multiSelectフィールドによるフィルタ

multiSelectタイプのフィールドでフィルタをかけるには、フィルタでフィールドのkeyと、項目の検索で対象とする可能性がある値を定義する必要があります。検索を実行すると、クエリでは基本的にOR演算が実行され、指定した値のいずれかがこのフィールドと一致するテンプレートが取得されます。

[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "category": [
        "online",
        "enterprise"
      ]
    }
  }
]

この例では、enterprise.contractテンプレートのインスタンスが適用されていて、キーcategoryのフィールドが値onlineまたはofflineに設定されているすべてのファイルとフォルダが検索されます。