メタデータクエリフィルタ

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

メタデータクエリフィルタ

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タイプのフィールドでフィルタをかけるには、gt (より大きい) や lt (より小さい) の値を指定して範囲を定義する必要があります。厳密な値を検索する場合は、gtltの両方に同じ値を入力できます。

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

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

数値に基づいてクエリを作成する場合は、-16777215~+16777215の範囲を超えないようにしてください。数値属性を使用したメタデータ検索では、インデックス値がFLOAT32として保存されます。結果として、-16777215~+16777215の整数は正確に表すことができます。この範囲外の数値を扱う処理では、精度が失われる場合があります。

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

dateタイプのフィールドでフィルタをかけるには、フィルタでフィールドのkeyと、項目の検索対象範囲を定義する必要があります。この範囲を定義するには、gt (より大きい) とlt (より小さい) の値を指定します。gtltはその値を含むことに注意してください。

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

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

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またはenterpriseに設定されているすべてのファイルとフォルダが検索されます。