制限

制限

メタデータクエリAPIには、いくつかの制限が適用されます。

ファイルとフォルダ

​メタデータクエリで返されるのは、リクエストしているユーザーがpreviewer以上のアクセス権限を持つ項目 (ファイルまたはフォルダ) のみです。

会社のテンプレートとグローバルテンプレート

メタデータクエリは、その会社によって作成されたメタデータテンプレートでのみ動作します。クエリでは、​global.propertiesテンプレートに保存された自由形式のキー/値ペアのコンテンツに基づく結果が返されません。

分類メタデータテンプレート

Boxでは、メタデータテンプレートを使用してコンテンツの分類を行うことができます。これらのメタデータテンプレートはメタデータクエリでは使用できません。なぜなら、大きな結果セットに関する問題が発生する可能性が高いためです。詳細は次に説明しています。

当面、将来これらのクエリのサポートを開始する計画はありません。

推奨される結果セットのサイズ

可能であれば、結果セットの項目数が2,000未満になるリクエストのみを送信することをお勧めします。結果セットは、リクエストするユーザーの権限と​ancestor_folder​スコープが考慮される前に、​from​​query​および​query_params​パラメータの評価だけに基づいてメタデータクエリに一致するファイルとフォルダのコレクション全体です。

結果セットの項目数が2,000を超えるメタデータクエリリクエストを送信した場合、APIは、以下の条件が両方とも満たされる場合に一致する結果をすべて返すことのみを保証できます。

  1. リクエストするユーザーが、結果セットに含まれるすべての項目に対してプレビューアー以上の権限を持っていること。
  2. 先祖フォルダに、結果セット内のすべてのファイルが含まれていること。

結果セットの項目数が2,000を超えており、上記の条件が当てはまらないメタデータクエリリクエストを送信すると、APIは、返される結果が少なくなるようクエリを制限する必要があることを示すレスポンスコード4XXとともにエラーを返す可能性があります。

たとえば、次に示す、catalogImages​というメタデータテンプレートの簡略化したレプリゼンテーションを考えてみます。これには、​photographerという文字列フィールドが1つあります。

{
  "templateKey": "catalogImages",
  "fields": [
    {
      "type": "string",
      "key": "photographer"
    }
  ]
}

この例では、10人のphotographer (写真家) がいて、それぞれがcatalogImages​テンプレートが適用されている同じ数の画像を取り込むとします。

ここで、Box Enterpriseに、catalogImagesテンプレートが適用され、2つのフォルダParts​Productsに均等に分けられている、4,000個のファイルがあると考えてみます。この2つのフォルダは、以下に示すように親フォルダ​Catalog​の子です。

Catalog/
|
|- Parts/
   |
   |- file_0000.jpeg
   |- ...
   |- file_1999.jpeg
|- Products/
   |
   |- file_2000.jpeg
   |- ...
   |- file_3999.jpeg

以下の表に、考えられるいくつかのクエリの結果を示します。クエリについては、読みやすくするために平易な言葉で説明しています。

結果セットは、リクエストするユーザーの権限と​ancestor_folder​スコープが考慮される前に、​from​​query​および​query_paramsパラメータの評価だけに基づいてメタデータクエリに一致する項目 (ファイルとフォルダ) のコレクションとして定義されることに注意してください。

クエリ結果セット結果
catalogImagesテンプレートが適用されている、写真家がMikeの項目を選択します。200項目成功Mikeに対応する項目のみを選択することで、結果セットはたった400ファイルに抑えられます。
catalogImagesテンプレートが適用されている項目を選択します。4,000項目失敗する可能性あり結果セットは2,000項目を超えます。ユーザーが結果セット内のすべてのファイルにアクセスできない場合は、クエリが失敗する可能性があります。
Products​フォルダにある、catalogImagesテンプレートが適用されている項目を選択します。4,000項目失敗する可能性あり結果セットは2,000項目を超えます。すべての結果が先祖フォルダに含まれるわけではありません。
Productsフォルダにある、catalogImagesテンプレートが適用されている、写真家がMikeの項目を選択します。200項目成功Mikeに対応する項目のみを選択することで、結果セットはたった400ファイルに抑えられます。