CMS API：ビデオ検索v2

はじめに

CMS APIで使用される動画検索のバージョン2は、新規の連携に推奨される構文です。日付範囲（.. と [a TO b] の両方の形式）、NOW、相対オフセット、カンマ区切りの値、リファレンスIDの前方一致など、v1 の検索で広く使われている機能をサポートしています。既存の q による連携がある場合は、ビデオ検索 v2 への移行準備を参照してください。バージョン1については、CMS/Playback API: ビデオ検索を参照してください。

どの構文を使用するかは、適切なURLパラメーターを選択するだけです。

• 新しいv2検索を使用するには：

      .../videos?query={search_string}

• 元の検索を使用するには：

      .../videos?q={search_string}

ベーシック

検索文字列の基本要素は 検索語であり、その前にフィールド名を付けることができます。フィールド名が含まれている場合、そのメタデータフィールドのみが検索されます。それ以外の場合は、いくつかのフィールド（以下に列挙）が検索されます。

例は次のとおりです。

検索するフィールド名を指定しない場合、リクエストは次の8つのフィールドでその値を検索します。

• id
• name
• description
• long_description
• tags
• reference_id
• custom_fields（すべてのカスタムフィールドをまとめて検索します）
• variants

検索でサポートされているフィールドは次のとおりです。

上記のどちらの例でも、関連するフィールドに「bird」という単語が含まれていない動画が返される可能性があります。次のセクションでは、検索結果を指定した用語を持つ動画のみに制限する方法について説明します。

無視される単語

特定の単語は非常に一般的であるため、検索文字列では無視され、実際の検索内容とは関係のない多くの結果が返される可能性があります。以下は、検索で無視される単語のリストです。

"a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"

また、ハイフン、アンダースコア、改行、 "$"、 "&"、 "*" などの英数字以外の文字は、単語の区切り文字として扱われます。例えば、 small-town のような検索文字列は small town として扱われます。

ステミングとは?

ステミングをサポートするビデオフィールドは、検索語の語幹を共通に持つ単語を返します。また、ステミングでは、部分的な単語ではなく、単語全体の入力のみがサポートされます

• 例 1: running を検索すると、running, run, runs を含む結果が返されます。
• 例 2: vid で検索しても、video を含む結果は返されません。

ステミングを使った検索は、次のフィールドで機能します。

• custom_fields
• description
• name
• long_description
• tags
• labels

高度な検索

検索結果を必要な動画に限定するのに役立つ修飾子がいくつかあります。

フレーズ検索

引用符で囲むことにより、（単一の単語ではなく）フレーズを検索することができます。

• "blue heron"
• name:"blue heron"

値を引用符で囲む

引用符はフレーズ検索のためだけのものではありません。英数字、アンダースコア、ピリオド以外の文字を含むフィールド値は、すべてダブルクォーテーションで囲んでください。特に、スペースまたは次の文字を含む値は必ず囲んでください。

:   /   |   =   $   %   &   !   *

このリストは網羅的なものではなく、例示です。確実な判断基準は上記の規則です。値が英数字、アンダースコア、ピリオドだけで構成されていない場合は引用符で囲んでください。たとえばアポストロフィはリストにありませんが、この規則の対象です。

引用符で囲まない場合の結果は、文字によって2通りに分かれます。

値が分割される文字

スペース、または / | = $ のいずれかがあると、値が分割されます。最初の部分は指定したフィールドに対する検索として残りますが、それ以降の部分は8つのデフォルトフィールドに対するフリーテキスト検索になります。エラーは返らないため、誤った結果に気付かないことがあります。

tags:women's health は、タグ women's とフリーテキスト health を検索するため、意図よりも多くの動画が返ることがあります。tags:"women's health" は1つのタグを検索します。逆の方向もあります。tags:$gaeilge は、指定したタグではなく別のタグ（gaeilge）を検索します。

クエリが解釈できなくなる文字

値の中の : または * は、まったく解釈できません。この場合リクエスト全体が HTTP 400 で拒否され、問題のある文字とその位置を示すメッセージが返ります。tags:modelid:414 は拒否されますが、tags:"modelid:414" は目的の動画を返します。クエリを解析できない場合を参照してください。

上記のリストの残りの文字（% & !）も、結果は場合によって異なりますが、同じ理由で引用符で囲んでください。引用符で囲むことが、すべての場合において正しい唯一の対処です。

ワイルドカードはサポートされません

アスタリスクはテキスト値のワイルドカードではありません。日付範囲や数値範囲で境界を開く * は別ですが、値の中のアスタリスクは解釈できないため、tags:spring* は「spring」で始まるすべてのタグに一致するのではなく、HTTP 400（unexpected input '*' at position 11）で拒否されます。

対処は、アスタリスクをどういう意図で使っていたかによって異なります。

• 探している値そのものにアスタリスクが含まれる場合は、クエリが有効なまま保たれるよう引用符で囲んでください：tags:"spring*"。ただし、照合されるテキストでは記号は単語の区切り文字として扱われるため（無視される単語を参照）、アスタリスク自体で一致が絞られるわけではありません。
• ワイルドカードとして使っていた場合は、削除してください。値の先頭部分で一致させたい場合は、設計上前方一致する reference_id を使用してください（下記を参照）。前方一致に対応するフィールドは他にありません。

タグのリスト

カンマ区切りのタグのリストは、いずれかの値を持つ動画に一致します。

    tags:sea,mammal

これは sea または mammal のタグを持つ動画を返します。

どの文字に引用符が必要かは、値を引用符で囲むを参照してください。

カスタムフィールドのリスト

カスタムフィールドの値もカンマ区切りにでき、同じく「いずれかの値」という意味になります。

    +product_number:H517497,H517498

これは product_number がいずれかの値である動画に一致します。

リファレンスIDによる検索

reference_id は他の文字列フィールドとは動作が異なります。引用符で囲まない値は、その値に等しい、またはその値で始まるリファレンスIDに一致し、完全一致が上位に並びます。大文字小文字は区別されません。

したがって、前方一致のためにアスタリスクを付ける必要はありません。reference_id:abc だけで前方一致になり、reference_id:abc* はサポートされません。

再生可能な動画

現時点で視聴者が再生できる動画に結果を限定する方法は2つあります。

playable_only パラメーター

    .../videos?query=name:bird&playable_only=true

playable 検索語

    .../videos?query=%2Bplayable:true%20name:bird

どちらも同じ定義を適用します。動画が再生可能とみなされるのは、次の4つすべてが満たされる場合です。

• complete が true である（レンディションが少なくとも1つ存在する）
• state が ACTIVE である（INACTIVE、PENDING、DELETED の動画は除外されます）
• schedule.starts_at が過去である、または設定されていない
• schedule.ends_at が未来である、または設定されていない

公開期間が設定されていない動画は、他の条件が満たされていれば再生可能とみなされます。

日付/時刻

日付範囲は、次の2つの形式のいずれかで指定できます。

• ブラケット構文：updated_at:[2020-01-01T00:00:00.000Z TO 2020-12-31T00:00:00.000Z]
• 短縮構文：updated_at:2020-01-01..2020-12-31

両方の境界値が範囲に含まれます。どちらの形式でも、日付、日付/時刻、NOW を使用できます。相対オフセットは2つの形式で扱いが異なる唯一の値の種類のため、後述の専用セクションで説明します。

ミリ秒とタイムゾーン

ミリ秒は省略できます。指定する場合は3桁が一般的な形式です（2019-09-30T14:24:33.512Z）。6桁も使用できます。

2つの構文には、タイムゾーン指定子に関して1つだけ違いがあります。

• ブラケット構文では Z が必須です。したがって時刻は常にUTCになります。
• 短縮構文では、Z または数値のUTCオフセットのいずれかを使用できます：updated_at:2026-08-07T14:30:47-07:00..NOW。オフセットは ±HH:MM の完全な形式である必要があります。±HH および ±HHMM は使用できません。

時刻を含まない日付

下限として使用した yyyy-MM-dd はその日の開始を意味します。上限として使用した場合は、どちらの構文でもその日全体が範囲に含まれます。したがって、次の2つはいずれも12月31日に作成されたすべての動画に一致します。

created_at:2020-12-31..2020-12-31
created_at:[2020-12-31 TO 2020-12-31]

オープンエンドの範囲

短縮構文では、どちらかの端を省略できます。

• created_at:2020-01-01.. ある日付以降
• created_at:..2020-01-01 ある日付まで

ブラケット構文では、開いている側に * を使用します：created_at:[2020-01-01 TO *]。

相対オフセット

相対オフセットは、符号、数値、単位で構成され、現在時刻を基準に計算されます：updated_at:-7days..NOW。

使用できる単位は YEAR(S)、MONTH(S)、DAY(S) または D、HOUR(S) または H、MINUTE(S) です。大文字小文字は区別されませんが、1つだけ例外があります。短縮構文では、1文字の M は曖昧なものとして拒否され、1文字の小文字 m は分を意味します。ブラケット構文は拒否せず、M を月として解釈します。どちらの場合も1文字に頼らず、MINUTE(S) または MONTH(S) と綴ってください。

以下は、日付/時刻検索文字列のサンプルです。

クエリを解析できない場合

検索文字列が本ページの構文に従っていない場合、リクエストは HTTP 400 で拒否され、何を読み取れなかったかとその位置を示すメッセージがレスポンス本文に返ります。

unexpected input ':' at position 12

この拒否をコードで判定する場合は、メッセージ文字列で判定してください。メッセージを包むJSON構造は検索の契約には含まれず、変更される場合があります。カウントエンドポイントも同じ検索文字列を同じ方法で拒否します。

メッセージの読み方

• 位置は0から始まります。デコード後の検索文字列の先頭からの文字数です。tags:modelid:414 の場合、位置12は2つ目のコロンです。
• ほとんどの場合、メッセージは2つの形式のいずれかです。使用できない位置に何かが現れた場合は unexpected input '<text>' at position <n>、閉じられていない括弧などで文字列が途中で終わっている場合は unexpected end of input at position <n> です。
• 一部のチェックは独自のメッセージを返します。代表的な例は相対オフセットで説明している、曖昧な相対時間単位です。

既知の問題

• ページングを行う場合は、常に sort パラメーターを指定してください。指定しない場合、結果は関連度順に並びます。関連度順はページングに十分安定していないため、同じ動画が2つのページに表示されたり、どのページにも表示されないことがあります。ときおり報告される検索結果の重複は、これが原因です。

  どのソートフィールドを指定しても順序は安定します。ただし updated_at でソートすると、ページング中に更新された動画が、すでに取得したページの後ろに移動する可能性があります。動画の取りこぼしが許されない連携では created_at でソートしてください。

• 検索レスポンスには合計件数が含まれません。クエリに一致する動画の件数が必要な場合は、同じクエリをカウントエンドポイント（/counts/videos）に送信してください。正確な件数が返ります。検索結果の1ページから合計を推測しないでください。