Job search API 參數：最佳做法 (v3)

設定 API

影響搜尋結果的因素

「精選職缺」、「啟用放寬功能」和「停用關鍵字比對」這些因素會大幅影響傳回給求職者的職缺數量和關聯性。您應根據業務需求適當設定這三項要素。如想找出最合適的設定，最好的方式是在測試階段套用於不同測試情境，並評估成果。

1. 精選職缺：您可使用精選職缺為個別職缺賦予宣傳價值，特別突顯對您業務需求較為重要的職缺。如需最佳做法和導入詳細資料，請參閱精選職缺一文。

2. disableKeywordMatch：這個參數能讓 API 傳回關鍵字相符項目，以及機器學習演算法判定為相關的搜尋結果。預設為 false。如保留預設值，表示 CTS Job search API 並非按機器演算法判定的關聯性來傳回職缺結果，而是按標題或工作說明中有關鍵字與求職者的查詢字串相符來傳回結果。如果將這個參數設為 true，則會停用關鍵字比對，而系統傳回的職缺數量也會較少 (只傳回機器學習功能判斷為相關的職缺)。

3. enableBroadening：這個參數能讓您放寬求職者對地點和工作類別的指定限制，從而擴充求職者的查詢範圍。預設值為 false；如設為 true 則代表啟用這項參數，可用來增加傳回的搜尋結果數量。

搜尋設定結果

只傳回最相關的職缺：將 disableKeywordMatch 設為 true，並將 enableBroadening 設為 false。 這個設定能改善 API 有關搜尋關聯性的效能指標，因為屆時系統將只傳回相關聯的職缺。 不過，搜尋結果中傳回的職缺數量整體上也會減少。

傳回更多有關聯且關鍵字比對相符的職缺搜尋結果：將 disableKeywordMatch 設為 false，並將 enableBroadening 設為 false。在搜尋結果中，相關職缺後面將列出關鍵字相符結果，但不會傳回查詢擴充結果。

傳回更多有關聯且擴充了查詢範圍的職缺：將 disableKeywordMatch 設為 true，並將 enableBroadening 設為 true。求職者的查詢可擴充為包含相關工作類別及附近地點，列在相關結果後面；而關鍵字相符項目將不會傳回。

儘可能傳回最多職缺結果：將 disableKeywordMatch 設為 false，並將 enableBroadening 設為 true。在 Job Search API 傳回的搜尋結果中，頂端是最相關的職缺，隨後則是關鍵字比對相符的職缺及查詢擴充的職缺 (按地點、工作類別或其他原則擴充)。這項設定能盡量增加傳回的職缺總數。

diasableKeywordMatch	enableBroadening	結果
-	-	傳回更多有關聯且關鍵字比對相符的職缺搜尋結果 (但假設精選職缺設為「false」)。
+	+	傳回更多有關聯且查詢擴充的職缺 (但假設精選職缺設為「false」)。
-	+	儘可能傳回最多職缺結果 (但假設精選職缺設為「false」)。
+	-	只傳回最相關的職缺 (但假設精選職缺設為「false」)。

Request.page_size

為獲得最佳效能並避免延遲狀況，請將結果頁面一次顯示的職缺數量設為 20 筆以下。

customAttributes

customAttributes 提供較大的設定彈性，能讓您根據業務需求 (例如 GPA 分數) 來為職缺指定額外的值，並運用這些值來篩選結果。

注意： 請避免設定任何與位置相關的 customAttributes 值。 API 現有的地點篩選器已經有內建演算法能自動偵測與求職者搜尋查詢相關的地點資訊。

地點欄位

如要進一步查看地點欄位的總覽資訊，請前往「地點欄位」頁面。在地址欄位中，提供工作街道地址比提供 GPS 座標更有助於改善 API 的地點偵測結果及搜尋關聯性。

locationFilter

假如同一間公司開出多個位於不同地理地區的職缺，請使用 regionCode。為每筆人才招聘項目指定 regionCode，可確保搜尋查詢只傳回求職者指定地點內的職缺，而不是傳回該公司在全球各地開出的職缺。舉例來說，假如未指定 regionCode，則搜尋地區關鍵字「劍橋」時，系統將一併傳回有關「英國劍橋」和「美國麻薩諸塞州劍橋」的結果，這會降低搜尋關聯性。

Region_code 和 Language_code

根據使用者搜尋的地理位置 (例如英國) 來設定 request.filters.location_filters.region_code。接著，依據該地理位置將 request.filters.language_code 設為適當的語言代碼 (在本例中應設為 en_GB)，API 才能使用本地化搜尋邏輯。舉例來說，美國用語中的「truck driver」(貨車司機)，在 en_GB 中的慣用說法是「lorry driver」。

radiusinMiles

這個參數可設定求職者指定地點的方圓距離 (以英里為單位)。API 將傳回這個地理區域範圍內的結果。對搜尋結果的地理位置套用指定距離的方式取決於求職者輸入的地點資訊類型。舉例來說，假如求職者輸入街道地址，系統就會從單點設定 radiusInMiles 距離；如果求職者輸入的是城市，API 就會對城市周邊套用定界框，然後從方框邊緣計算距離；而若使用者只輸入州/省或國家/地區，系統將直接忽略 radiusInMiles。

請儘可能縮短里程半徑。如果設定的里程距離過長，可能會傳回超出求職者指定地點範圍之外的結果，導致關聯性降低。舉例來說，如果 radiusInMiles 設為 100 英里，則搜尋紐約市的工作時，系統將傳回搜尋範圍涵蓋紐約上州及紐澤西州的結果。因此，儘可能縮短半徑有助於提高搜尋結果的關聯性。

postingExpireTime

這個參數可設定職缺招募有效期限長度，到期後該職缺就不會再顯示於搜尋結果中。預設到期日為職缺建立後的 30 天 (使用世界標準時間)。

Job_employment_type

使用 Job_employment_type 可提高職缺搜尋結果關聯性，但這不是必填欄位。

設定 API：自訂排名

您可以藉由精選職缺來影響搜尋結果，只要指定單一變數 (promotionValue) 就可以突顯特定職缺；詳情請參閱精選職缺說明文件。自訂排名則可讓您透過多項變數來影響搜尋結果，不論關聯性為何都能進一步控制排名；對於需要平衡考量關聯性與經濟利益因素的應用程式來說 (例如多層級的單次點擊出價訂閱者系統)，這項功能相當實用。除了關聯性分數以外，「rankingExpression」和「importanceLevel」這兩個變數也會影響職缺搜尋結果的排名。

• rankingExpression：這個變數可根據現有關聯性分數來排名職缺 (由 API 演算法判定)。「rankingExpression」必須設為「filterable」(可篩選)，API 才能為參數建立索引。

• importanceLevel：這個參數會在系統傳回搜尋結果時，替職缺設定排名上的重要程度，共有「未指定」、「NONE」、「LOW」、「MID」、「HIGH」和「EXTREME」六個不同的層級。將值設為 EXTREME 時，系統將會忽略所有其他 API 產生的關聯性因素，因此請謹慎使用。求職者查詢傳回的搜尋結果最上方將顯示設為「EXTREME」的職缺，而不是最相關的職缺。

• 精選職缺與自訂排名：精選職缺會顯示在關聯性排名上方，最適合用來宣傳同一類的職缺，例如某間公司的職缺。如果您除了關聯性排名，還需要根據多層級單次點擊出價變數來排名職缺，則建議採用自訂排名。

通勤條件搜尋

通勤時間搜尋功能可讓求職者根據通勤時間來搜尋職缺。 如要啟用這項功能，請在 JobQuery.commuteFilter 欄位中額外納入 CommuteFilter 物件。這個物件可讓求職者選取 commuteMethod、travelDuration 和 startCoordinates，且計算通勤時間時，求職者還能選取 roadTraffic (TRAFFIC_FREE 或 BUSY_HOUR) 及 departureTime 等選項。詳情請參閱通勤時間搜尋功能導入方式及教學頁面。

資料管理和錯誤處理

資料完整性

1. 上傳職缺：資料方面的問題可能會導致職缺無法上傳到 API。詳情請參閱 HTTP 回應碼頁面。以下是一些常見的例子：

   • 職缺地區不正確，因此無法解析要求。
   • 公司或職缺欄位不存在，因而傳回錯誤的要求。

   排解職缺上傳問題的方法主要有以下三種：

   • 從後端檢查記錄
   • 使用 CTS 管理工具來查看資料記錄。
   • 在 Cloud Console 上設定 Stackdriver Monitoring 工具，以收集中繼資料、指標和事件。

2. 建立職缺索引：Job search API 可用來為特定時段內上傳的所有職缺建立索引。不過，您的系統端可能會有配額限制。傳送職缺至 CTS 之前，請務必先確認您系統對於索引建立要求的相關限制。

錯誤處理機制

自我引發的分散式阻斷服務攻擊會導致求職者遭到封鎖，如要避免這種情況，關鍵就在於錯誤處理機制。透過網際網路提供的 API 服務也可能發生間歇性連線失敗、長時間中斷、突然進行服務維護，以及其他需要用戶端應用程式重試 API 要求的事件。重試時必須採用網路友善行為，例如指數輪詢。

刪除重複項目

重複的職缺項目可能會對求職者造成負面的搜尋體驗，Job search API 提供以下兩項有助盡量避免重複項目的功能：

1. 建立職缺：如果您使用下列條件建立超過 2 個職缺，記錄將會遭拒且您會遇到 4xx 錯誤：

   • 相同的 companyName, AND
   • 相同的 job_req_id, AND
   • 相同的地區/languageCode

2. 搜尋職缺：CTS Job search API 可顯示與求職者搜尋查詢相關的工作。 關聯性演算法的內建功能可確保系統傳回多元化職缺，避免近似相同的職缺相鄰顯示在搜尋結果中。