打造能查賽程、近期戰績與積分榜的足球聊天機器人

Piotr Grudzień
發布日期 閱讀時間約 10 分鐘
在 Quickchat AI 裡的兵工廠三行賽事簡報,旁邊是顯示 Free 訂閱方案的 football-data.org Account Settings 頁面

您正圍繞著兵工廠客場對陣紐卡索聯的比賽來安排週六行程。一位在紐約的朋友需要開球時間。接著,群組聊天中有人問起兵工廠上次客場踢得如何。第一個問題的答案就在賽程表上。至於第二個問題,您得知道「利物浦 0,兵工廠 1」這個比分中的那一球是誰進的。

您將打造 Matchday Notebook,這是一款足球聊天機器人,可查詢接下來三場英超賽程、讀取兵工廠近五場聯賽賽果,並找出他們在積分榜上的位置。此範例的時間點定在 2026 年 11 月 18 日。客場對紐卡索聯的比賽排在 11 月 21 日星期六 17:30 UTC,即 紐約時間下午 12:30。

Native Stats 中的紐卡索聯賽事以及 Quickchat AI 中對應的比賽日答案 資料提供者的比賽頁面和私密 Agent 的開球時間一致。這個 Quickchat AI 對話是根據一份有特定日期的公開紀錄重現資料來執行的,您可以在下方重現。

查看紐卡索聯賽事 或 下載 Matchday Notebook 套件。將其解壓縮並執行 python3 replay.py,不需帳號即可查看三場賽程、五場賽果和積分榜。同一個套件中也包含了 Action 設定和用於連接您自有資料來源的 Main Prompt。

1. 聊天機器人將追蹤哪個俱樂部和賽事?

先鎖定俱樂部和聯賽。兵工廠的聯賽戰績可能會因為您是否計入週二晚間的歐戰而有所不同。在此筆記本中,兵工廠是指球隊 57,而聯賽則是指英超聯賽 2021,其代碼也稱為 PL。

  1. 開啟 football-data.org 註冊表單。輸入您的名字和電子郵件地址,接受條款並選取 Create account。在涵蓋範圍列表上查看您的聯賽。免費方案包含英超聯賽,提供延遲的賽程和比分。

football-data.org 註冊表單,包含名字和電子郵件欄位、Create account 按鈕及 Free Tier 詳細資訊 請使用您能查看的電子郵件地址。註冊後,football-data.org 會將 API 金鑰寄到該信箱。免費方案允許每分鐘 10 次請求。

如果您已有帳戶,請用您的電子郵件和 API 權杖登入。若需要權杖的另一份副本,請用您註冊的地址透過電子郵件申請。請保留此權杖,以供步驟 2 的受保護標頭使用。

football-data.org 的 Account Settings 頁面,顯示 Free 訂閱方案及部分 Available competitions 列表 在 Subscription 下方查看您的方案,並在 Available competitions 下方尋找您的聯賽。此擷取畫面顯示歐洲冠軍聯賽 (CL) 和德國足球甲級聯賽 (BL1)。

  1. 要追蹤另一個俱樂部,請在賽事的球隊列表中查找,例如 GET /v4/competitions/PL/teams。在下面的比賽請求中使用返回的球隊 ID 和賽事 ID。v4 快速入門同時包含這兩種查找。
  2. 建立 Quickchat AI Agent,將其命名為 Matchday Notebook,並在測試時保持私有。您需要有可用的點數用於對話和模擬。開啟 Identity → AI Persona → Main Prompt 並貼上以下說明。螢幕截圖和可複製的設定使用英文。

Native Stats 中的阿森納俱樂部頁面和 Quickchat AI 中 Matchday Notebook 的 Identity 設定 在兩個地方保持相同的俱樂部。在產品中,Agent 的說明位於 Identity 下。

複製 Matchday Notebook Main Prompt
You are Matchday Notebook, an Arsenal Premier League companion. Use get_club_fixtures for the schedule, get_recent_results for form and get_league_standings for the league table. For match reads, use an inclusive UTC start date and an exclusive end date. Ask for dates when the window is unclear.

List up to the requested number of TIMED or SCHEDULED fixtures in kickoff order. Give the date, time and timezone; say when the hour is unconfirmed. Flag postponed or cancelled games separately. For form, sort FINISHED matches newest first, take up to five and read full-time scores home first. Judge wins, draws and losses from Arsenal's side. For standings, find Arsenal (team 57) in the TOTAL table. Give the season, position, games played and points.

Keep answers short. Link a match to https://native-stats.org/match/ID using its returned ID, and the Premier League table to https://native-stats.org/competition/PL/. Attribute football-data.org, give the relevant date and identify any snapshot as a snapshot. Quote a retrieval time only if supplied. Keep null scores unknown. Report empty windows, missing scores and failed reads accurately. Stop after a rate limit. Do not predict scores.

2. 如何取得兵工廠的下一場賽程?

從能回答群組聊天中關於開球時間問題的 Action 開始。一次請求即可回傳兩支俱樂部、預定時間和比賽狀態。此處的狀態篩選器請保持開放,這樣延期的比賽仍能顯示。一筆 TIMED 狀態的紀錄會有開球時間。若是 SCHEDULED 狀態,請告知使用者時間尚待確認。

  1. 開啟 Actions & MCPs → Add Action → API Action → Create manually。將 API Action Name 設為 get_club_fixtures,並將 When to run 設為 AI decides。在 What to ask the user first 底下,新增必要的 Text 輸入 date_from 和 date_to,兩者皆設為 No default。它們的描述分別是「要包含的第一個 UTC 日期,格式 YYYY-MM-DD」和「要排除的第一個 UTC 日期,格式 YYYY-MM-DD」。
  2. 對於 API Endpoint,選擇 GET 並輸入以下 URL。開啟 Query Params 並將 competitions 設定為字面值 2021。新增 dateFrom 和 dateTo。對於每個值,使用 Add AI Data → Parameters 插入匹配的日期輸入。將 Body 留空。
  3. 將以下描述貼到「API Action Description」下方並儲存 Action。在「Headers」下方,憑證將會顯示在唯寫的 X-Auth-Token 列中。請在發出第一個請求之前設定好。新增第二個一般標頭,其中 Accept 作為金鑰,application/json 作為值。在所有三個 Action 上使用相同的兩個標頭。
https://api.football-data.org/v4/teams/57/matches

football-data.org Team matches 路由以及 Quickchat AI GET 端點,使用 Query Params 查詢 2021 賽季和兩個日期 依照供應商參考資料中的球隊賽事路徑設定動作。兵工廠固定在網址中,聯賽在 Query Params 中,而兩個日期則來自對話。

複製賽程 Action 描述
Use for Arsenal's upcoming Premier League fixtures in the requested date window. Sort by utcDate ascending. Show TIMED or SCHEDULED matches and flag postponements or cancellations separately. State the window if fewer fixtures are returned.

在供應商的請求範例中,API 金鑰是放在 X-Auth-Token。請在 get_club_fixtures 的 Headers 中使用相同的標頭名稱。

公開的 football-data.org Sign in 表單、v4 X-Auth-Token 範例以及 Quickchat AI 中的 Headers 標籤 登入表單需要您的電子郵件和 API 權杖。在 Quickchat AI 中,只有權杖會放入受保護的 X-Auth-Token 列。

請私下輸入權杖。 儀表板可以取代已儲存的密鑰。若要一開始就將該標頭設為唯寫,每個 Action 僅需連接一次帳戶。請在 ChatGPT 或 Claude 中,使用 Quickchat AI 設定指南 連接您的帳戶。要求已連接的助理依下方指示,準備一個帶有無害標記的標頭。接著請自行開啟 Action 的 Headers 標籤頁,將同一列中的值換成您的 football-data.org 原始權杖,然後選取 Save changes。重新開啟編輯器,確認該值顯示為 [redacted]。請將權杖保存在儀表板中,切勿在對話中透露。

On Matchday Notebook, set the X-Auth-Token header of get_club_fixtures to the literal value REPLACE_IN_DASHBOARD with is_secret=true. Preserve the rest of the settings. Read the Action back and confirm that the header is secret and the value is [redacted]. Stop before testing.

賽程 Action 中的 Headers 標籤頁,顯示已隱藏值的 X-Auth-Token 這是已儲存的標頭。供應商預期的是權杖本身,不含 Bearer 前置詞。

嘗試首次讀取。 在 Test Response → Test the API 中,提供開始日期以及您所需結束日期的後一天。然後啟用 Action,並在 AI Preview 中詢問該時間範圍內接下來的三場聯賽賽程。若要即時建置,請選擇未來的日期。封存範例使用了 2026-11-18 和 2026-12-03,因此 12 月 2 日晚間的賽事也被計入。您可以開啟來源連結,查看最近一場比賽的資訊。v4 日期篩選參考資料 中說明了結束日期不包含在內的規則。

11 月 18 日(含)至 12 月 3 日(不含)之間的三個賽程日期 在這筆資料回放中,11 月 21 日客場對戰紐卡索,11 月 29 日主場迎戰曼城,12 月 2 日客場對戰布倫特福德。如果請求的結束日期設為 12 月 2 日,就會漏掉對布倫特福德的比賽。

3. 如何讀取兵工廠近五場比賽的戰績?

此範例中最關鍵的比賽結果是利物浦 0,兵工廠 1。如果聊天機器人每次都把第一個數字當成兵工廠的得分,就會將一場客場勝利誤判為落敗。請讓所有比分都維持主場在前的順序,並以球隊 ID 來判斷兵工廠的表現。

  1. 建立第二個 API Action,命名為 get_recent_results。使用相同的 GET 端點、日期輸入、日期篩選標籤和賽事篩選器。新增查詢列 status,並填入字串值 FINISHED。
  2. 設定以下描述。重複 get_recent_results 的唯寫標頭設定,檢查遮罩並啟用 Action。
  3. 要求查詢指定時間範圍內最近的五場聯賽。以本範例而言,請使用 2026 年 10 月 1 日至 11 月 17 日。在選取五場比賽前,請先依 utcDate 排序。如果該時間範圍只回傳三場比賽,就顯示這三場,並詢問是否要擴大搜尋範圍。
複製戰績 Action 的描述
Use for Arsenal's recent Premier League form in the requested date window. Sort FINISHED matches newest first, then take up to five. Use both full-time goals and the home and away team IDs to judge each result from Arsenal's perspective.

來源賽事頁面顯示利物浦 0,兵工廠 1,並標示出兵工廠的客場得分 先在客隊欄找到兵工廠,再讀取客場進球數。利物浦的零分代表對手成功零封。

從最近一場開始看戰績。 兵工廠以 1–0 擊敗赫爾城,客場以 1–0 戰勝利物浦,以 2–0 擊敗艾佛頓,客場以 1–0 戰勝諾丁漢森林,並以 2–1 擊敗里茲聯。總計五連勝,進7球失1球。對利物浦的賽事紀錄 是個很好的測試案例,因為獲勝方排在後面。

在儲存的測試資料中,回傳的列表刻意以里茲聯的比賽為開頭,赫爾城的比賽為結尾。依開球時間排序會將赫爾城的比賽移至答案的頂端。請開啟對話旁的 Action 回應,並比較兩個列表中的第一場和最後一場比賽。

兵工廠五場已完成的比賽,按日期順序顯示主客場比分 五連勝的背後可能隱藏著重要細節。其中兩場是客場比賽,因此代表獲勝的得分數字在右邊。

4. 聯賽排名和積分從何而來?

五連勝能反映最近幾週的表現。但聯賽排名還取決於此前的所有比賽以及其他所有球隊的戰績。請為您的 Agent 提供一個獨立的積分榜 Action。

  1. 將其命名為 get_league_standings。選擇 GET,貼上以下端點,並將輸入、查詢參數和內文留空。使用 AI decides,新增以下描述,並為此 Action 重複唯寫標頭的設定。
  2. 在 Test Response 中,於 standings 內尋找 type 為 TOTAL 的項目。在該項目的 table 中,找到 team.id 等於 57 的資料。啟用 Action ,然後問「兵工廠在英超積分榜上排在哪裡?」
  3. 將 position、playedGames 和 points 與相同賽季和日期的來源資料進行比較。11 月 18 日時,Native Stats 的英超積分榜 顯示排名第1,已賽10場,積分27分。您目前的積分榜會隨著其他球隊的比賽而變動。
https://api.football-data.org/v4/competitions/PL/standings
複製積分榜 Action 描述
Use for the current Premier League table. Find team ID 57 in standings where type is TOTAL. Report season, position, playedGames and points. If the row is missing, say the position is unavailable.

兵工廠在英超積分榜上排名第一的該列資料,以及筆記本所使用的欄位 閱讀 TOTAL 中的單一行。27 分涵蓋了快照中的所有十場聯賽比賽。

5. 您能追溯比賽日簡報的來源嗎?

開始一段全新的 AI Preview 對話。先問接下來的三場賽程,接著問「我們最近五場聯賽表現如何?」,提供戰績的時間範圍,然後再問「那樣我們在積分榜上排第幾?」在 Inbox 中,為每個答案打開已呼叫的 Action 標記。透過 Action 的 View logs,您可以比較參數和回應與球迷看到的內容。建立 API Action 的指南 會說明這些控制項的位置。

若要取得文章開頭顯示的綜合比賽日摘要,請使用儲存範例中的日期來提出以下問題。若要取得最新摘要,請使用即將到來的日期查詢賽程,並使用最近的日期查詢戰績。

Arsenal briefing for 18 Nov 2026: next away kickoff this week (UTC), last five since 1 Oct, and table position. Three short lines.

在 Quickchat AI 中呼叫賽程 Action 的請求與回傳的賽事紀錄 檢查呼叫中的日期和賽事 ID。在這筆本機資料回放中,560651 是對紐卡索的賽程。

為了可重複的檢查,打開 Conversations → Testing,建立一個資料集並儲存這三個問題。新增以下所示的兩個邊界問題。更改 Action 描述後運行資料集,並檢查呼叫和回覆。使用受控回應來練習罕見狀態或錯誤。單獨的假設性問題測試答案的措辭。

在 Quickchat AI 中,包含賽程、近況、積分榜和邊界測試問題的 Matchday Notebook 資料集 每次編輯後都使用相同的問題。客場比賽的結果能抓出全主場測試會遺漏的計分錯誤。

測試案例球迷應該聽到的內容
一場比賽被延期,兩個進球都是 null。這是一場平局嗎?這場賽事已延期,沒有記錄比分。
成功的搜尋回傳了空的 matches 列表。這代表整個賽季都沒有比賽嗎?在該時間範圍內沒有找到任何比賽。請提供您搜尋的日期。
提供者返回 401 或 403。查詢失敗。請檢查已儲存的權杖和賽事涵蓋範圍。
資料來源回傳 429。已達到請求次數上限,請稍後再試。

畫面顯示 Quickchat AI 的視窗無內容,以及一筆成功但未回傳任何賽事的請求。 即使視窗無內容,請求本身仍是成功的。此時助理可提議放寬日期範圍。

如要再次確認開球時間的變動,可對照聯賽官方的賽程修改公告。請務必一併記下原定日期、時區以及查詢當下的日期。免費的資料來源更新速度可能不及轉播單位,如果球迷需要根據這個答覆來安排週六行程,這點就格外重要。

Football data provided by the Football-Data.org API. 此處的過往範例使用了該資料來源的公開 Native Stats 頁面。關於目前的服務範圍和資料更新頻率,請參閱方案與請求次數上限。

常見問答

我可以使用哪個足球 API 來建立賽程聊天機器人?

football-data.org v4 API 提供所涵蓋賽事的賽程、賽果和積分榜。使用球隊的比賽端點來查詢賽程和近期戰績,並使用賽事的積分榜端點來查詢聯賽排名。

football-data.org 的免費方案是否提供即時比分?

免費方案包含延遲的比分和賽程、所涵蓋賽事的聯賽積分榜,以及每分鐘 10 次的 API 請求。每次回答時請附上來源和日期,如需即時比分,請檢查您的方案。

如何將兵工廠更換為其他球隊?

在 football-data.org 中找到該俱樂部的球隊 ID 和賽事。在兩個比賽 Action 中替換球隊 57,更改數字賽事篩選器和積分榜 URL,然後更新說明中的俱樂部名稱和球隊 ID。用一場您認得的賽程進行測試。

如何從球隊的視角取得最近五場比賽的結果?

篩選指定日期範圍內已結束的聯賽,按開球時間從最新到最舊排序,最多取五場。對於每場比分,在判定勝、平或負之前,先確認您的球隊是主場或客場出賽。如果符合條件的比賽少於五場,則顯示您找到的場數。

延期比賽的空白比分是什麼意思?

空白比分表示提供者沒有提供該隊的總進球數。保持比賽狀態可見,並讓比分未知。零比零平局需要一場已完成的比賽,並記錄兩個零。

如何將足球賽的開球時間轉換為我的時區?

從比賽的 UTC 開球時間開始,使用如 America/New_York 的指定時區,並在答案中保留日期。日光節約時間和日曆日的變更都可能影響顯示的時間。

Quickchat AI Quickchat AI Ask Quickchat AI a question