本頁面由 Cloud Translation API 翻譯而成。

篩選媒體搜尋

如果你有媒體搜尋應用程式，可以使用中繼資料篩選搜尋查詢。本頁說明如何使用中繼資料欄位，將搜尋範圍限制在特定文件集。

事前準備

請務必建立媒體應用程式和資料儲存庫，並擷取資料。詳情請參閱「建立媒體資料儲存庫」和「建立媒體應用程式」。

文件範例

請參閱這些媒體文件範例。閱讀本頁內容時，您可以隨時參考這些定義。

{"id":"172851","schemaId":"default_schema","jsonData":"{\"title\":\"Avatar: Creating the World of Pandora (2010)\",\"categories\":[\"Documentary\"],\"uri\":\"http://mytestdomain.movie/content/172851\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}
{"id":"243308","schemaId":"default_schema","jsonData":"{\"title\":\"Capturing Avatar (2010)\",\"categories\":[\"Documentary\"],\"uri\":\"http://mytestdomain.movie/content/243308\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}
{"id":"280218","schemaId":"default_schema","jsonData":"{\"title\":\"Avatar: The Way of Water (2022)\",\"categories\":[\"Action\",\"Adventure\",\"Sci-Fi\"],\"uri\":\"http://mytestdomain.movie/content/280218\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}
{"id":"72998","schemaId":"default_schema","jsonData":"{\"title\":\"Avatar (2009)\",\"categories\":[\"Action\",\"Adventure\",\"Sci-Fi\",\"IMAX\"],\"uri\":\"http://mytestdomain.movie/content/72998\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}

篩選運算式語法

請務必瞭解用於定義搜尋篩選器的篩選運算式語法。篩選運算式語法可歸納為下列擴充巴科斯諾爾形式：

  # A single expression or multiple expressions that are joined by "AND" or "OR".
  filter = expression, { " AND " | "OR", expression };
  # Expressions can be prefixed with "-" or "NOT" to express a negation.
  expression = [ "-" | "NOT " ],
    # A parenthetical expression.
    | "(", expression, ")"
    # A simple expression applying to a text field.
    # Function "ANY" returns true if the field contains any of the literals.
    ( text_field, ":", "ANY", "(", literal, { ",", literal }, ")"
    # A simple expression applying to a numerical field. Function "IN" returns true
    # if a field value is within the range. By default, lower_bound is inclusive and
    # upper_bound is exclusive.
    | numerical_field, ":", "IN", "(", lower_bound, ",", upper_bound, ")"
    # A simple expression that applies to a numerical field and compares with a double value.
    | numerical_field, comparison, double );
    # Datetime field
    | datetime_field, comparison, literal_iso_8601_datetime_format);
  # A lower_bound is either a double or "*", which represents negative infinity.
  # Explicitly specify inclusive bound with the character 'i' or exclusive bound
  # with the character 'e'.
  lower_bound = ( double, [ "e" | "i" ] ) | "*";
  # An upper_bound is either a double or "*", which represents infinity.
  # Explicitly specify inclusive bound with the character 'i' or exclusive bound
  # with the character 'e'.
  upper_bound = ( double, [ "e" | "i" ] ) | "*";
  # Supported comparison operators.
  comparison = "<=" | "<" | ">=" | ">" | "=";
  # A literal is any double quoted string. You must escape backslash (\) and
  # quote (") characters.
  literal = double quoted string;
  text_field = text field - for example, category;
  numerical_field = numerical field - for example, score;
  datetime_field = field of datetime data type - for example available_time;
  literal_iso_8601_datetime_format = either a double quoted string representing ISO 8601 datetime or a numerical field representing microseconds from unix epoch.

篩選媒體搜尋結果

如要使用中繼資料篩選媒體搜尋結果，請按照下列步驟操作：

找出資料儲存庫 ID。如果已有資料商店 ID，請跳到下一個步驟。
1. 前往 Google Cloud 控制台的「AI Applications」頁面，然後在導覽選單中點選「Data Stores」。
  
  前往「資料儲存庫」頁面
2. 點按資料儲存庫的名稱。
3. 在資料儲存庫的「資料」頁面中，取得資料儲存庫 ID。
找出要篩選的文件欄位。舉例來說，對於「開始前須知」中的文件，您可以使用 categories 欄位做為篩選條件。

篩選運算式只能使用可建立索引的欄位。如要判斷欄位是否可建立索引，請執行下列操作：
1. 前往 Google Cloud 控制台的「AI Applications」頁面，然後在導覽選單中點選「Data Stores」。
  
  前往「資料儲存庫」頁面
2. 點按資料儲存庫的名稱。
3. 在「名稱」欄中，按一下資料儲存庫。
4. 按一下「結構定義」分頁標籤，即可查看資料儲存庫的結構定義。如果欄位的「可建立索引」為：
  - 選取，然後即可篩選該欄位以進行搜尋；請略過步驟 3。
  - 未選取，然後按照步驟 3 啟用欄位索引。
  - 如果選項為「not_available」，則該欄位無法編入索引。
如要讓欄位 (例如 categories 欄位) 可供篩選，請執行下列操作：
1. 前往 Google Cloud 控制台的「AI Applications」頁面，然後在導覽選單中點選「Apps」。
  
  前往「應用程式」頁面
2. 按一下媒體搜尋應用程式。
3. 在導覽選單中，按一下「資料」。
4. 按一下 [Schema] (結構定義) 分頁標籤。這個分頁會顯示目前的欄位設定。
5. 按一下 [編輯]。
6. 如果尚未選取，請在「類別」列中勾選「可建立索引」核取方塊，然後按一下「儲存」。
7. 請等待六小時，讓結構定義編輯作業生效。六小時後，即可繼續進行下一個步驟。

取得搜尋結果。

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search:search" \
-d '{
"query": "QUERY",
"filter": "FILTER"
}'

更改下列內容：

PROJECT_ID：您的專案 ID。
DATA_STORE_ID：資料儲存庫的 ID。
QUERY：要搜尋的查詢文字。
FILTER：文字欄位，可使用篩選器運算式篩選搜尋結果。

舉例來說，假設您想在「開始前」部分搜尋電影，且搜尋結果只須符合下列條件：(1) 含有「avatar」一詞，且 (2) 屬於「Documentary」類別。如要這麼做，請在呼叫中加入下列陳述式：

"query": "avatar",
"filter": "categories: ANY(\"Documentary\")"

詳情請參閱 search 方法。

按一下即可查看範例回覆。

如果您執行類似上述程序的搜尋，預期會收到類似以下的回覆。請注意，回應只會包含《阿凡達》紀錄片。

{
  "results": [
    {
      "id": "243308",
      "document": {
        "name": "projects/431678329718/locations/global/collections/default_collection/dataStores/rdds3_1698205785399/branches/0/documents/243308",
        "id": "243308",
        "structData": {
          "categories": [
            "Documentary"
          ],
          "title": "Capturing Avatar (2010)",
          "uri": "http://mytestdomain.movie/content/243308",
          "media_type": "movie"
        }
      }
    },
    {
      "id": "172851",
      "document": {
        "name": "projects/431678329718/locations/global/collections/default_collection/dataStores/rdds3_1698205785399/branches/0/documents/172851",
        "id": "172851",
        "structData": {
          "categories": [
            "Documentary"
          ],
          "uri": "http://mytestdomain.movie/content/172851",
          "media_type": "movie",
          "title": "Avatar: Creating the World of Pandora (2010)"
        }
      }
    }
  ],
  "totalSize": 2,
  "attributionToken": "XfBcCgwIvIzJqwYQ2_qNxwMSJDY1NzEzNmY1LTAwMDAtMmFhMy05YWU3LTE0MjIzYmIwOGVkMiIFTUVESUEqII6-nRXFy_MXnIaOIsLwnhXUsp0VpovvF6OAlyKiho4i",
  "guidedSearchResult": {},
  "summary": {}
}

篩選可用的文件

如要讓搜尋結果只傳回可用的文件，您需要在查詢中加入這項篩選條件。如果 available_time 是過去的日期，且 expire_time 未指定或設為未來日期，即為有效文件。

篩選條件，只傳回目前可用的文件：

  available_time <= \"DATE_TIME\" AND expire_time > \"DATE_TIME\"

將 DATE_TIME 替換為今天的日期，例如 2025-04-21 或 2025-04-21T00:00:00Z。

依評分、人物和機構篩選

媒體分級、人物和機構的篩選器語法獨一無二，不適用上述模式。請參考下列範例和可複製的篩選器程式碼片段，為評分、人物和機構建立篩選器。

篩選器會因您使用的是 Google 預先定義的架構或自訂架構而有所不同。

評分、個人和機構的篩選器 (Google 預先定義的結構定義)

評分、人員和機構篩選器的語法和範例如下：

依分級篩選：依特定來源的分級篩選。
```
 rating(RATING_SOURCE, aggregate_ratings.rating_score) OPERATOR RATING_SCORE
```
更改下列內容：
- RATING_SOURCE：評分的來源。如果是預先定義的結構定義，這是 aggregate_ratings.rating_source 欄位中的值。
- OPERATOR：比較運算子，可以是 <=、<、>=、> 或 =
- RATING_SCORE：[1,5] 範圍內的評分值。如果是預先定義的架構，這是 aggregate_ratings.rating_score 欄位中的值。
範例：這個篩選器會將搜尋範圍限制在 IMDB 評分高於 2 顆半星的電影。括號內的值會解析為 IMDB 評分的值：
```
"filter": "rating(imdb, aggregate_ratings.rating_score) > 2.5"
```
篩選使用者：針對特定角色篩選使用者名稱。
```
person(PERSONS_ROLE, persons.name): ANY NAME_STRING
```
更改下列內容：
- PERSONS_ROLE：如果是預先定義的結構定義，這是 persons.role 欄位中的值 (director、actor、player、team、league、editor、author、character、contributor、creator、editor、funder、producer、provider、publisher、sponsor、translator、music-by、channel 或 custom-role)。
- NAME_STRING：一或多個具有指定角色的人員名稱。如果是 curl 指令 (例如步驟 4)，則需要使用反斜線字元逸出雙引號。
範例：這項篩選器會將搜尋範圍限制為由布萊德彼特或凱特溫斯蕾主演的電影。
```
filter: "person(actor, persons.name): ANY(\"Brad Pitt\", \"Kate Winslet\")"
```
篩選機構：針對特定角色篩選機構名稱。
```
org(ORG_ROLE, organization.name): ANY NAME_STRING
```
更改下列內容：
- ORG_ROLE：如果是預先定義的結構定義，這是 organizations.role 欄位中的值 (director、actor、player、team、league、editor、author、character、contributor、creator、editor、funder、producer、provider、publisher、sponsor、translator、music-by、channel 或 custom-role)。
- NAME_STRING：一或多個具有指定角色的機構名稱。如果是 curl 指令 (例如步驟 4 中的指令)，雙引號需要使用反斜線字元逸出。
這個範例會將搜尋範圍限制為製作機構為 Walt Disney Studios 的電影：
```
filter: "org(producer, organizations.name): ANY(\"Walt Disney Studios\")"
```

評分、個人和機構的篩選器 (自訂結構定義)

如果您使用自訂結構定義，請先查看「Google 預先定義的結構定義」一節，然後查看本節中的範例。如要讓自訂結構定義中的評分、人員和機構篩選器正常運作，必須正確設定屬性對應。如要瞭解屬性對應，請參閱「自訂結構定義」。

篩選器	要對應的屬性
評分	`media_aggregated_rating` `media_aggregated_rating_score` `media_aggregated_rating_source`
使用者圖示	`media_person` `media_person_name` `media_person_role`
組織	`media_organization` `media_organization_name` `media_organization_role`

自訂結構定義的評分篩選器範例

這個篩選條件會搜尋爛番茄評為 5 星的電影：

"filter": "rating(rotten_tomatoes, custom_rating.star_score) = 5"

rotten_tomatoes 是對應至 media_aggregated_rating_source 的欄位值。custom_rating.star_score 是對應至 media_aggregated_rating.media_aggregated_rating_score 鍵屬性的欄位。

自訂結構定義的機構篩選器範例

這個篩選條件會搜尋配樂由倫敦交響樂團或好萊塢工作室交響樂團演奏的電影。

"filter: org(music-by, company.id): ANY (\"London Symphony Orchestra\", \"Hollywood Studio Symphony\" )

company.id 是對應至 media_organization_name 屬性的欄位名稱。而 music-by 是公司記錄欄位中的值，會對應至 media_organization_role。

篩選媒體搜尋 透過集合功能整理內容 你可以依據偏好儲存及分類內容。