Shopify 在 2026 年 11 月 6 日啟用新的 bulk operations 存取要求:由 Partner 建立的 public app 與 custom app,在執行 GraphQL Admin API 的大量查詢或大量異動前,必須先於 Partner Dashboard 開啟對應權限。bulkOperationRunQuery 與 bulkOperationRunMutation 分成兩項,不是核准其中一項就能同時執行另一項;未取得權限的請求會回傳 access denied。

這是前一波 IP allowlist 要求之後的實質新進展,但兩者不能混為同一個開關。IP allowlist 限制 Admin API token 可以從哪些網路使用;bulk operation 權限則限制 App 能不能啟動大量工作。只完成 allowlist,沒有開啟 bulk query 或 mutation,工作仍會失敗;反過來取得 bulk 權限,也不能取代 11 月的網路來源限制。

哪些 App 會受影響

影響範圍是 Partner 建立、且會執行 bulk operations 的 public app 與 custom app。商家直接在 Shopify Admin 或 Dev Dashboard 建立的 App,目前不需要走這個啟用流程。要求適用所有 GraphQL Admin API 版本,因此不能靠暫時固定在舊版 API 避開。

Shopify 已替近期執行過 bulk operations 的 App 預先開啟相應存取,不代表之後永久有效。官方文件指出,某一類 operation 若連續 31 天沒有啟動,該類型的存取會失效,下一次使用前必須重新啟用。低頻的月結匯出、季節性商品匯入、年度盤點或災難復原工作,比每日同步更容易踩到這個條件。

先把每個 job 依用途標成 query 或 mutation。商品、訂單、客戶資料的大量匯出通常屬於 query;大量建立或更新資料則屬於 mutation。不要只看程式檔名或排程名稱判斷,應搜尋實際呼叫的 GraphQL mutation,並確認是否還有臨時維運腳本、舊版 worker 與不同 region 的部署。

上線前先做權限與工作清冊

在 Partner Dashboard 進入 App 的 API access requests,於 Run bulk operations 區塊確認 Allow bulk queries、Allow bulk mutations 的狀態。只勾實際需要的類型,並記錄檢查日期、操作者、App、環境與對應 job。官方說明此設定不需要發布新版 App,也不需要要求商家重新安裝,權限會套用到該 App 的所有安裝商店。

接著建立一份可執行清冊,至少包含 shop、operation 類型、觸發方式、正常頻率、資料範圍、owner、預估完成時間、完成 webhook 與重跑策略。若同一 App 幾個月才跑一次 mutation,排程前應先有權限預檢,而不是等到真正處理商家資料時才發現 access denied。

驗收要在 dev store 或受控測試商店分別啟動一個小型 query 與 mutation,確認 GraphQL 回應沒有 user error,並保存回傳的 bulk operation ID。之後用 bulk_operations/finish webhook 或狀態輪詢確認完成,再下載 query 結果或核對 mutation 結果。Webhook 可能延遲或未送達,正式流程仍應有帶退避的狀態查詢與逾時告警。

Access denied 不要直接重送大量工作

收到 access denied 時,先區分三層問題:App 是否取得 bulk 類型權限、查詢內的欄位是否具備一般 Admin API scope,以及請求來源是否符合 IP allowlist。三者可能顯示相近的權限錯誤,但修復方式不同。自動化若不分類就無限重試,只會增加 API 流量,並可能讓 queue 持續堆積。

權限失效時,暫停新的 bulk job,保留游標、輸入檔版本與 operation key,通知 App owner 到 Partner Dashboard 重新啟用。恢復後先用小資料集測試,再從明確 checkpoint 續跑。Bulk mutation 應為每批資料建立冪等鍵或外部處理紀錄,不能只因第一次沒有收到完成通知就重新提交整批,否則可能重複更新庫存、價格或標籤。

若需求只是少量即時讀寫,普通 GraphQL query 或 mutation 搭配分頁、節流與重試可能更容易觀察;大量匯出、批次同步與避免客戶端自行管理高量 pagination 時,bulk operation 才有優勢。選擇依資料量、完成時效與錯誤恢復能力決定,不是所有背景工作都應改成 bulk。

與 IP allowlist 一起驗收

使用 bulk operations 的 public app 還要留意 Shopify 對 IP allowlist 設定的最早期限。啟動器、狀態輪詢器、完成 webhook 後的下載 worker,可能分散在不同服務;其中會持 token 呼叫 Admin API 的每個出口都要納入網路清冊。Bulk 權限開啟成功,不代表新的 serverless region 或臨時 migration runner 已被允許。

建議把部署 gate 做成兩段:第一段確認 Partner Dashboard 的 query/mutation 權限與 allowlist 狀態;第二段在 dev store 實際執行最小工作,確認啟動、完成通知、結果下載及失敗恢復。對低頻 job,在執行前一日再跑一次預檢,並準備不修改資料的 dry run 或小批次模式。

完成條件應包括:每個 bulk job 都知道自己需要哪一類權限、31 天未使用時有重新啟用流程、access denied 能分辨 operation 權限、API scope 與網路限制、重跑不會造成重複異動,且 query 與 mutation 都有獨立測試。這次變更不是 Shopify Bulk API 停止服務,而是把大量操作改成顯式、可失效的能力;把權限生命週期納入排程,才能避免低頻同步在真正需要時突然中斷。