Excel Power Query API：在 Excel 使用 Narwhal API

藉由 Excel 的 Power Query 和 Narwhal，你可以把國定假日、發布日期、經濟數據、大宗商品現貨價格、外匯匯率和預測市場機率拉取到活頁簿中。你的 Narwhal 帳號和 API 金鑰適用於這些資料 API，活頁簿開啟期間 Excel 還可以重新整理這些查詢。

你將完成的設定

Power Query 是 Excel 發送 API 請求並讀取 JSON 回應的途徑。完成後，你的活頁簿裡會有想要資料的查詢，比如國定假日表或 Brent 現貨價格。實際使用時，每個領域對應一個查詢。範例通篇使用相同的基礎 URL 和 Authorization 標頭，只是每個領域的路徑和回應欄位不同。Narwhal 的 CPI、通膨、GDP 和殖利率等經濟數據也使用同一個帳號。

設定你的 API 金鑰

  1. 建立免費金鑰 在 Narwhal 註冊頁建立免費金鑰。這裡用到的資料 API 共用一個帳號和一把 API 金鑰。REST 和 MCP 共用該金鑰，Excel 範例把它放在 REST 請求中傳送。
  2. 把金鑰保存在環境變數中 把金鑰存入名為 NARWHAL_API_KEY 的環境變數。在 Power Query M 範例中，把 Authorization 標頭裡的 YOUR_KEY 替換成你的金鑰。標頭的值以 Bearer 開頭，後面接金鑰。
  3. 不要公開活頁簿 由於 Authorization 標頭寫在 M 程式碼裡，Power Query 會把金鑰儲存在活頁簿內部。試算表裡請使用免費金鑰，並且不要分享該檔案。在這些範例中，環境變數並不能取代其中的金鑰值。

開啟空白查詢

  1. 開啟「取得資料」 在「資料」索引標籤中開啟「取得資料」，找到「從其他來源」，再選擇「空白查詢」。這些就是用來發起請求的 Power Query 控制項。
  2. 開啟進階編輯器 在進階編輯器中開啟這個空白查詢，並貼上下一節中的 M 程式碼。重新整理查詢之前，先把你的金鑰填入標頭。
  3. 選擇要傳回的結果 in 之後的運算式決定該查詢傳回什麼結果。完整範例傳回 Holidays。要得到對應的資料表，就傳回 Releases、Cpi、Fx 或 Fed；現貨價格則傳回 Brent。每個想要的領域各用一個獨立的查詢。

用 Power Query M 取得資料

在 Web.Contents 中保持 https://api.narwhalapi.com 不變。把端點路徑放在 RelativePath，參數放在 Query，這樣重新整理才能正常運作。Narwhal 輔助函式負責讀取 JSON 回應，每個運算式再選取對應領域的欄位。發布日期的運算式指定了輸出欄名，並使用 MissingField.UseNull。

這個輔助函式接受一個路徑和一個選用的查詢參數記錄。沒有提供查詢記錄時，它使用空記錄。Table.FromRecords 把記錄集合轉成資料表，Number.FromText 則處理 Brent 價格。請讓回應欄位的選取保持連在你所需領域的呼叫後面。

涵蓋六個領域的 Power Query M
let
    Narwhal = (path as text, optional query as record) =>
        Json.Document(Web.Contents("https://api.narwhalapi.com", [
            RelativePath = path,
            Query = if query = null then [] else query,
            Headers = [Authorization = "Bearer YOUR_KEY"]
        ])),
    Holidays = Table.FromRecords(Narwhal("v1/calendars/holidays/USA/2026")[holidays]),
    Releases = Table.FromRecords(
        Narwhal(
            "v1/economics/calendar",
            [countries = "USA", start_date = "2026-11-01",
             end_date = "2026-11-30", limit = "100"]
        )[releases],
        {"at", "period", "topic", "status"}, MissingField.UseNull),
    Cpi = Table.FromRecords(
        Narwhal("v1/economics/USA/cpi/observations", [start = "2025-09"])[observations]
    ),
    Brent = Number.FromText(Narwhal("v1/commodities/spot/BRENT/USD")[price]),
    Fx = Table.FromRecords(Narwhal("v1/fx/rates/USD", [currencies = "EUR,IDR"])[rates]),
    Fed = Table.FromRecords(
        Narwhal("v1/predictions/policy-paths/federal-reserve")[meetings]
    )
in
    // return Releases, Cpi, Fx or Fed the same way;
    // each area is its own query in practice
    Holidays

按排程重新整理活頁簿

用「資料」索引標籤中的「全部重新整理」來重新整理查詢。在查詢內容中，可以設定查詢在開啟檔案時重新整理，以及在檔案開啟期間每隔 N 分鐘重新整理一次。這些設定只對已開啟的活頁簿生效，所以要用定時重新整理，就得保持活頁簿處於開啟狀態。

Excel 沒有背景排程器。要無人值守執行，請使用 Power Automate 或 Excel 之外的腳本。設為開啟時重新整理的查詢，會在你再次開啟檔案時拉取資料；定時重新整理則取決於活頁簿是否保持開啟。請為需要重新整理資料的查詢逐個設定重新整理內容。

在 Excel 中查詢國定假日

從 holidays 欄位讀取美國 2026 年的國定假日。每個假日都有 date 和 name，Table.FromRecords 把這些記錄轉成資料表。此範例使用與完整範例相同的輔助函式和標頭，直接傳回國定假日資料表。作為獨立查詢使用之前，請先替換其中的金鑰。

美國國定假日資料表
let
    Narwhal = (path as text, optional query as record) =>
        Json.Document(Web.Contents("https://api.narwhalapi.com", [
            RelativePath = path,
            Query = if query = null then [] else query,
            Headers = [Authorization = "Bearer YOUR_KEY"]
        ]))
in Table.FromRecords(Narwhal("v1/calendars/holidays/USA/2026")[holidays])

在 Excel 中查詢發布日期

從 releases 取得美國 2026 年 11 月的經濟數據發布日期。傳回的欄位是 at、period、topic 和 status。請把國家和日期參數保留在 Query 記錄中。這個請求針對的是發布日曆；要查 CPI 的觀測期間和數值，請使用經濟數據查詢。

美國發布日曆
let
    Narwhal = (path as text, optional query as record) =>
        Json.Document(Web.Contents("https://api.narwhalapi.com", [
            RelativePath = path,
            Query = if query = null then [] else query,
            Headers = [Authorization = "Bearer YOUR_KEY"]
        ]))
in Table.FromRecords(
    Narwhal(
        "v1/economics/calendar",
        [countries = "USA", start_date = "2026-11-01",
         end_date = "2026-11-30", limit = "100"]
    )[releases],
    {"at", "period", "topic", "status"},
    MissingField.UseNull
)

在 Excel 中查詢經濟數據

以 2025 年 9 月作為起始參數，請求美國 CPI 觀測值。讀取 observations，即可在資料表中得到 period 和 value 欄位。在活頁簿中使用結果時，期間要和觀測值放在一起。請像完整範例那樣，把起始參數保留在 Query 中。

美國 CPI 觀測值
let
    Narwhal = (path as text, optional query as record) =>
        Json.Document(Web.Contents("https://api.narwhalapi.com", [
            RelativePath = path,
            Query = if query = null then [] else query,
            Headers = [Authorization = "Bearer YOUR_KEY"]
        ]))
in Table.FromRecords(
    Narwhal("v1/economics/USA/cpi/observations", [start = "2025-09"])[observations]
)

在 Excel 中查詢大宗商品現貨價格

從 price 讀取以 USD 計價的 Brent 現貨價格。這個回應欄位是價格，M 運算式用 Number.FromText 把它作為數字傳回。大宗商品現貨代碼例如 XAU、XAG、XPT、XPD、XCU、BRENT 和 WTI。此範例使用 BRENT。

以 USD 計價的 Brent 現貨價格
let
    Narwhal = (path as text, optional query as record) =>
        Json.Document(Web.Contents("https://api.narwhalapi.com", [
            RelativePath = path,
            Query = if query = null then [] else query,
            Headers = [Authorization = "Bearer YOUR_KEY"]
        ]))
in Number.FromText(Narwhal("v1/commodities/spot/BRENT/USD")[price])

在 Excel 中查詢匯率

以 USD 為基準貨幣，在 currencies 參數中請求 EUR 和 IDR。從回應中選取 rates，把記錄轉成資料表。每筆記錄都有 currency 和 rate，所以查詢結果裡貨幣始終與它的匯率並排。

USD 匯率
let
    Narwhal = (path as text, optional query as record) =>
        Json.Document(Web.Contents("https://api.narwhalapi.com", [
            RelativePath = path,
            Query = if query = null then [] else query,
            Headers = [Authorization = "Bearer YOUR_KEY"]
        ]))
in Table.FromRecords(Narwhal("v1/fx/rates/USD", [currencies = "EUR,IDR"])[rates])

在 Excel 中查詢預測市場機率

拉取聯準會政策路徑，並從回應中讀取 meetings。每次會議都有 resolves_at、p_cut、p_hold 和 p_hike。此範例把會議作為資料表傳回，結算時間和政策機率都可以當作欄位使用。如果想在活頁簿中使用這些機率，就把它作為獨立查詢。

聯準會政策路徑
let
    Narwhal = (path as text, optional query as record) =>
        Json.Document(Web.Contents("https://api.narwhalapi.com", [
            RelativePath = path,
            Query = if query = null then [] else query,
            Headers = [Authorization = "Bearer YOUR_KEY"]
        ]))
in Table.FromRecords(Narwhal("v1/predictions/policy-paths/federal-reserve")[meetings])

為什麼 Power Query 會要求認證？

對該 Web 資料來源選擇「匿名」驗證。Power Query 只在匿名驗證下允許使用 Authorization 標頭。請求仍然會透過 M 程式碼裡的標頭傳送你的 Narwhal 金鑰；Web 資料來源的認證選項就是「匿名」。

可以把結果用於 NETWORKDAYS 嗎？

可以。把 NETWORKDAYS 的假日引數指向 Holidays 資料表的 date 欄。該引數使用查詢傳回的假日日期，name 欄存放的是假日名稱。美國國定假日範例請求的是 2026 年，所以其日期就是那一年的假日。需要這些假日日期的計算，都可以使用這個結果。

發布於 。

後續步驟