YouTube Data API v3 開通教學：從 Google Cloud、OAuth Testing 到品牌頻道唯讀驗證

2026-10-24 18:17:46 JST | Web | 3 Reads

Copyright Notice: This article is an original work licensed under the CC 4.0 BY-NC-ND license. If you wish to repost this article, please include the original source link and this copyright notice.
Source link: https://v2know.com/article/1442

想用本機程式整理 YouTube 影片標題、簡介與多語言版本，第一步是替程式建立可辨識的身分，並由頻道管理者授權。本文從 Google Cloud 的選單開始，依序完成 API 啟用、External／Testing、測試使用者、權限範圍、Desktop OAuth 用戶端，以及本機同意與頻道驗證。

先釐清：Testing 是 OAuth 應用程式的發布狀態，不是另一套「測試版 YouTube API」。Testing 授權仍可連到真實頻道；如果程式呼叫更新或刪除方法，影響的就是既有內容。因此，最後一關只讀取頻道資料，確認選對頻道後先停下來。

核對日期：2026 年 10 月 24 日。介面採英文版，中文說明附上英文按鈕名稱。本文使用實際操作時保留的原圖，並補充目前介面的脫敏離線截圖；專案與信箱均為教學示例。OAuth 同意流程圖另標為示意，沒有為補圖重新建立用戶端或重做授權。

開始前：先認識這幾個不同的東西

項目	用途	容易混淆的地方
Google Cloud 專案	集中管理啟用的 API、OAuth 設定與專案配額。	它不是 YouTube 頻道；專案名稱也不必等於頻道名稱。
Google Auth Platform	管理應用名稱、受眾、scope 與 OAuth clients。	Testing／In production 是這裡的發布狀態。
Desktop OAuth client	辨識這支本機程式，下載的 JSON 是其設定檔。	單靠 JSON 還不能代表頻道管理者完成同意。
Scope	程式向使用者要求的權限範圍。	在 Console 列出 scope，還需要程式實際要求、使用者實際同意。
Token	同意後供程式存取 API；refresh token 可在有效時換取新的 access token。	它與下載的 client JSON 是兩份不同的檔案。

請準備一個能管理目標 YouTube 頻道的 Google 帳號，以及對 Cloud 專案有足夠管理權限的帳號。它們可以是同一個，但 Cloud 專案權限與 YouTube 頻道權限各自獨立。公開資料查詢常能使用 API key；管理自己的影片則需要使用者 OAuth，本篇使用 Desktop app，不建立服務帳戶。

為了方便對照，下文把 Cloud 專案稱為 Harbor Demo、品牌頻道稱為「海港教學頻道」。[email protected] 只是圖片中的示例，不能拿來登入或加入測試名單；實際操作必須換成你自己的 Google 帳號。

步驟一：從首頁選定正確的 Cloud 專案

1. 開啟 Google Cloud Console 首頁，登入要管理設定的帳號。
2. 點左上角 Google Cloud 標誌旁的專案選擇器。彈出 Select a resource 後，在 Recent 或 All 清單中選專案。
3. 同名專案不一定是同一個專案。請比對 Project ID，不要只看名稱，也不要把 Project number 當成 Project ID。
4. 已有可用專案就沿用。完全沒有專案時，才點選擇器右上角 New project，填寫 Project name；Organization／Location 依你的帳號與組織實際可選項設定，最後按 Create，再切換到新專案。

後面每個設定都以目前選中的專案為準。若既有分析工具也使用這個專案，變更 Audience 的發布狀態會影響同專案的 OAuth clients；另建一個 Desktop client 並不會得到獨立的 Testing／Production 狀態。本文沿用 External／Testing。

單純開通本篇功能，不需要因首頁推薦而啟用 VM、儲存空間、Gemini 或其他付費產品，也不用為此啟用付費試用。若組織政策或 Console 出現額外要求，先確認要求適用的服務與專案。

步驟二：從 API Library 啟用 YouTube Data API v3

1. 點左上角三條線的 Navigation menu。
2. 在 Products 區找 APIs & Services，點它的文字進入服務頁。
3. 在服務頁左側點 Library；也可點頁面上方 Enable APIs and services。
4. 在 API Library 的搜尋框輸入 YouTube Data API v3，按 Enter，點開同名結果。
5. 新專案若尚未啟用，按 Enable。若看到 API Enabled 與 Manage，代表已啟用，直接繼續。

三條線是整個 Cloud 的導覽選單；產品名稱旁的小箭頭通常是開啟子選單，產品頁左上角的小圖示則可能只是收合側欄。若一點只把側欄縮小，請展開側欄，再點 Library 的文字。

管理影片標題、簡介及多語言 metadata，使用的是 YouTube Data API v3。YouTube Analytics API 與 YouTube Reporting API 處理分析／報表，無須為本篇一併啟用。Google 的入門文件也要求先在目標專案啟用 Data API，再處理需要使用者同意的方法。

步驟三：進入 Google Auth Platform，保留 External／Testing

進入路徑：Navigation menu → APIs & Services → OAuth consent screen。目前會進入 Google Auth Platform。若左側已經是 APIs & Services 的選單，直接點 OAuth consent screen 即可。

第一次設定應用程式時

1. 如果 Overview 顯示尚未設定，按 Get started。
2. 在 App Information 填 App name，例如「Harbor Creator Tools」。User support email 從下拉清單選自己的可用信箱。
3. 在 Audience 選 External。Internal 主要供 Google Cloud 組織內部使用；個人 Gmail 帳號通常走 External。
4. 在 Contact Information 填接收 Google 通知的聯絡信箱，依畫面完成所需確認，再建立應用設定。
5. 完成後進左側 Audience，核對 Publishing status 是 Testing、User type 是 External。

這段首次精靈依Google Auth Platform 官方建立流程說明，本次沒有在既有專案重跑。若已看到 Overview、Branding、Audience、Clients、Data Access 等選單，代表已有應用設定，不必再建一份；應用名稱與聯絡信箱可在 Branding 檢查。

本篇到 Testing 為止，不按 Publish app，也不按 Make internal。畫面若提示要完成 Branding 才能發布，是發布流程的條件，不代表必須先轉正式狀態才能由測試使用者授權。

步驟四：加入真正管理頻道的測試使用者

路徑：Google Auth Platform → Audience → Test users。

1. 往下捲到 Test users，按 Add users。
2. 填入稍後要登入授權的 Google 帳號信箱，依畫面按 Save。
3. 回到名單確認信箱正確。若帳號已在清單，就不必重複新增。

品牌頻道的名稱或聯絡信箱，不一定是能登入 Google 的帳號。要加入的是能管理該 Brand Account 的人所使用的 Google 帳號。Google 的Audience 說明確認：Testing 最多可列 100 位測試使用者，而受測試使用者管理的 Brand Account 可以進行授權。這個人數限制與 YouTube API 每日配額不同。

步驟五：在 Data Access 宣告 youtube.force-ssl

路徑：Google Auth Platform → Data Access → Add or remove scopes。

1. 按 Add or remove scopes，開啟 Update selected scopes 側面板。
2. 在清單找 youtube.force-ssl。若搜尋不到，捲到 Manually add scopes。
3. 貼入下方完整 scope，按 Add to table。
4. 確認表格中目標 scope 已勾選，沒有勾入無關權限，再按面板底部 Update。
5. 回到 Data Access 主頁後，還要按 Save。看到儲存成功提示，才完成這一步。

https://www.googleapis.com/auth/youtube.force-ssl

youtube.force-ssl 的能力包含讀取、編輯與永久刪除 YouTube 影片、評價、留言及字幕，遠大於「只改標題」。名稱中的 force-ssl 不表示它是唯讀權限。若只需要查詢，應另選 youtube.readonly；本篇選擇 force-ssl，是為後續經審閱的 metadata 修改作準備，但此次驗證仍只讀取。

Google 的 videos.update 文件列出可用的授權 scope，包括 youtube.force-ssl，並沒有把 youtube.upload 列在其中。不要因為將來也想上傳影片，就把 upload 當成修改既有 metadata 的替代範圍。

步驟六：建立 Desktop OAuth client，立即保存 JSON

路徑：Google Auth Platform → Clients → Create client。

1. 按 Create client，在 Application type 選 Desktop app。
2. 在 Name 填容易辨認的名稱，例如「Harbor Metadata Desktop」。這是 Console 中區分用戶端的名稱，與 Branding 的應用名稱不同。
3. 如果出現 Use this client for an AI-powered agent，請依程式實際用途及 Google 要求判斷。本次既有用戶端維持未勾選，教學不變更此標記。
4. 新設定確認無誤才按 Create。建立成功視窗中，立即按 Download JSON，把檔案存到自己的私人本機資料夾。
5. 下載後直接重新命名為 client_secret_youtube_metadata.json，保留副檔名，不改動內文。

AI-powered agent 標記用於識別代理程式用途，本身不會新增 scope。Google 目前要求混合一般與代理工作流程時分離 clients，部分 Google Workspace MCP 端點也要求 agentic client。它不是影片的 AI 內容標記；不能據此推論勾選就會被 YouTube 限流，或未勾選便能規避政策。詳見OAuth client 官方說明。

下載當下就保存，別假設之後一定能再次取得完整 secret。Google 現行說明指出，新 secret 的完整值只在建立時可見、可下載，之後可能只顯示末四碼。本文不提供建立成功視窗的圖片，也不展示任何真實 JSON。若已經完成下載，就不必另拍含憑證的畫面。

安全存放的示例結構如下。路徑是教學例子，請自行建立；不要照抄成公開 Git 專案、文章圖片資料夾或雲端同步資料夾。

C:\Private\CreatorApi\
  client_secret_youtube_metadata.json  ← 從 Console 下載
  .youtube_metadata_token.json         ← 程式在同意及頻道驗證後產生

檔案權限只開放給需要執行程式的本機使用者。不要把 JSON 內容貼進聊天、寄信或放進截圖；程式只需要知道完整路徑。若另有分析工具的 client／token，請分開保存並保留舊檔，不把兩份 token 互換。Desktop app 是 public client，不能靠藏住 client secret 取代 PKCE 與使用者同意；下載檔與 token 仍應妥善保護。

步驟七：先記下目標頻道 ID，再做本機 OAuth

一個 Google 帳號可能管理多個品牌頻道，登入正確的 Google 帳號，不等於已選對 YouTube 頻道。先在 YouTube 頭像選單切到目標頻道，再從 YouTube → 右上角頭像 → Settings（設定）→ 左側 Advanced settings（進階設定）查看 Channel ID。這是以 UC 開頭的固定 ID，不是 @handle、信箱或 Cloud 專案 ID；操作入口可對照查找使用者與頻道 ID 的官方步驟。

官方說明指出，查看這裡的 ID 需要以頻道主要擁有者登入；若你是其他管理者而看不到，請由擁有者提供正確的 Channel ID，不要猜測。品牌頻道與個人頻道可以使用不同名稱、頭像，也能由同一個 Google 帳號管理。先理解這層關係，可避免在授權選擇器誤選自己的個人頻道。參考Google 對頻道與 Brand Account 的說明。

準備 Python 與示例程式

Google 官方建議使用現成 OAuth 用戶端函式庫。隨文提供的 oauth_readonly.py 示例程式（ZIP，下載後解壓縮）使用 PKCE、loopback callback 與官方 Python 函式庫，只呼叫一次 channels.list，不包含影片更新、上傳或刪除。程式碼是供新讀者自行設定的範例，本文製作期間未用它讀取既有憑證或重做同意。

先安裝 Python，在存放示例程式的資料夾開啟 PowerShell，執行：

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install google-api-python-client google-auth-oauthlib google-auth-httplib2

把 JSON 放到前面的私人資料夾。下列命令中的 UC_你的目標頻道ID 必須換成剛才抄下的真實 Channel ID；示例佔位文字不會通過程式檢查。

.\.venv\Scripts\python.exe .\oauth_readonly.py `
  --workspace "C:\Private\CreatorApi" `
  --expected-channel "UC_你的目標頻道ID" `
  --authorize

--authorize 是明確啟動新一輪同意的參數，只在首次設定或確定需要重新同意時使用。若你已有自己的授權工具，沿用該工具的安全入口即可，不要為照本篇教學另建第三份 token。

瀏覽器裡要確認什麼

1. 讓本機程式開啟授權頁；不要手動拼 OAuth URL，也不要把授權網址轉貼出去。
2. 選擇已加入 Test users、且能管理目標頻道的 Google 帳號。密碼、二步驗證或安全確認由本人完成。
3. 若出現帳戶／頻道選擇畫面，選「海港教學頻道」這類目標 Brand Account 頻道，不要只因個人帳號排在第一個就直接點。
4. Testing 應用可能出現未驗證或測試存取提醒。先核對是否為自己建立的應用、正確的開發者與預期權限，確認後才繼續。陌生應用、額外權限或組織封鎖時先停下。
5. 在同意頁核對 YouTube 權限。它可能以「查看、編輯及永久刪除影片、評價、留言和字幕」之類的文字呈現；文字依語言而異，實際範圍必須與本篇 scope 相符。
6. 同意後，瀏覽器回到程式建立的 127.0.0.1 本機回呼頁。回到 PowerShell 看驗證結果，保持程式執行到結束。

這個短暫的 127.0.0.1 HTTP 回呼，是 Desktop OAuth 的 loopback 機制；它不表示你要替外網架站或購買主機。程式應自行處理 state、PKCE 與授權碼交換，不要求使用者把 code 貼回聊天。技術細節見YouTube 的 Desktop OAuth 官方指南。

步驟八：先做唯讀驗證，成功後就停下來

示例程式在儲存新 token 前，會以目前授權執行：

youtube.channels().list(part="id,snippet", mine=True).execute(num_retries=0)

mine=True 讀取的是目前授權身分對應的頻道。程式把回傳 ID 與你事先提供的目標 ID 比對；一致才保存 token。Google 的 channels.list 文件說明，此方法為 GET 查詢，每次消耗 1 個配額單位。

成功結果的格式如下，這裡只是示例輸出：

{"status": "valid", "channel_match": true, "youtube_write_calls": 0}

若顯示 Channel mismatch，先停下來確認品牌頻道選擇與帳號權限；程式不會保存這次新 token，也不會修改影片。若沒有頻道回傳，請檢查該帳號是否確實管理目標頻道；單純受邀操作 Studio 的權限不應直接當成 API 一定可用的保證。

之後檢查既有授權，使用同一命令但拿掉 --authorize：

.\.venv\Scripts\python.exe .\oauth_readonly.py `
  --workspace "C:\Private\CreatorApi" `
  --expected-channel "UC_你的目標頻道ID"

這會在需要且允許時正常更新 access token，再向 API 核對頻道。token 檔案存在、瀏覽器顯示同意完成、或舊的成功紀錄，都不能取代本次 API 驗證。本案例製作教學時，另以既有授權程式完成了唯讀頻道核對；沒有為補圖重新 OAuth，也沒有執行 YouTube 寫入。

Testing 的七天，到底是哪裡到期？

在 External／Testing 下，本篇包含 YouTube scope 的使用者同意會自同意時間起七天到期；即使取得 refresh token，它也受這個期限約束。只有單純使用基本個人資料類 scope 的例外，不能套用到 youtube.force-ssl。依據見Google 的 Testing 到期規則。

看到的情況	代表什麼	處理方式
Access token 正常到期	短效存取憑證需更新；不一定要重新登入。	由程式在 refresh token 仍有效時正常 refresh。
Testing 同意滿七天	原本的同意／refresh token 可能已到期。	確認狀態後重新同意；refresh 不會把七天重新起算。
invalid_grant	授權可能遭撤銷、到期或因其他政策失效。	辨識原因，避免反覆重試同一份失效 token。
配額不足或暫時網路錯誤	不等於 OAuth 七天到期。	處理配額／連線問題，不急著重新 OAuth。

In production 不受 Testing 的固定七天期限，但不等於 refresh token 永久有效，也不等於已完成 Google 驗證。撤銷、長期未用、token 數量限制等仍可能使授權失效，參考Google 的 token 失效說明。本文保留 Testing；未來若改變發布狀態，應重新檢視整個專案的其他 clients 與驗證要求，不在本篇順手切換。

每日排程可以檢查有效性、在允許時 refresh，也可以在到期時提醒本人；它不能保證每七天完全無人操作，更不能把刷新 access token 說成「自動延長 Testing」。需要本人登入、同意或驗證時，仍應由本人完成。

配額、費用與真實寫入，要分開看

配額是 API 的使用額度，不是 OAuth 的有效期限，也不是頻道的測試開關。同專案的 clients 共用對應的專案 API 配額；另建 Desktop client 不會多送一份。到 Navigation menu → APIs & Services → Enabled APIs & services → YouTube Data API v3 → Quotas & System Limits 查看；依 Console 版本，分頁也可能簡寫為 Quotas。把每日總量、當日已用、剩餘量及每分鐘限制分開核對。

截至核對日期，官方配額表列出的預設配置如下。實際專案可能不同，不能把預設額度當作自己目前的剩餘額度。

方法／配額桶	目前官方預設或成本	用途
其他一般端點共用桶	每日 10,000 units	例如頻道讀取與 metadata 更新。
channels.list、videos.list	每次 1 unit	唯讀查詢；分頁、重試也會增加用量。
videos.update	每次 50 units	更新既有影片 metadata，會改動真實內容。
search.list	獨立桶預設每日 100 次；每次 1 quota	不要沿用舊文章「每次 100 units」估算新制。
videos.insert	獨立桶預設每日 100 次；每次 1 quota	上傳方法，不是修改舊片標題的方法。

Google 在 2026 年 6 月的修訂紀錄說明開始拆分搜尋與上傳的配額桶。每日額度於美國太平洋時間午夜重設；不是日本或台灣午夜。無效請求也有成本，分頁的下一次請求另計；有每日額度仍須遵守專案的速率限制。

例如，50 支影片若各合併成一次 videos.update，寫入部分就是 50 × 50＝2,500 units；事前讀取、衝突比對與事後回讀要另外計算。這是估算範例，不是本文替任何影片執行的工作量。標題與多語言內容能否合併，仍取決於程式實際提交的 part 與資料。

開通這個 API 不要求你為本篇另外購買運算或儲存資源；Cloud 首頁的試用金與付費產品不是 YouTube API quota 的替代品。需要更多配額時，應依官方申請／審查程序處理，不能把「綁卡」當作自動買到更多額度。

Testing 不是沙盒，唯讀測試也不會證明寫入一定成功。取得 force-ssl 後，程式仍可能有權限修改或刪除真實資料。未來第一次寫入，應先指定影片、產生完整預覽與原值快照，審閱後才執行，再用 API 回讀確認。尤其 videos.update 會依提交的 part 覆寫可修改欄位，漏送既有值可能造成資料被移除；不要把只想改一個標題的測試寫成不完整的整段 snippet。

完成時，逐項確認這八件事

1. 目前選中的是預期的 Cloud 專案，YouTube Data API v3 已啟用。
2. Google Auth Platform 顯示 External／Testing。
3. 真正管理目標頻道的 Google 帳號已在 Test users。
4. Data Access 已保存 youtube.force-ssl，程式請求與實際同意範圍相符。
5. 用戶端類型是 Desktop app；client JSON 已保存於私人資料夾。
6. JSON、token、OAuth code 都沒有出現在公開專案、文章或截圖中。
7. 唯讀 channels.list(mine=True) 的回傳 ID 與目標品牌頻道一致。
8. 知道 Testing 七天後可能需要重新同意；任何內容寫入另行準備與審閱。

做到這裡，代表本機工具具備可驗證的授權入口。先保留這份成功的唯讀結果，再開始規劃你真正想批次處理的影片與文字。

This article was last edited at 2026-10-24 18:22:21 JST

Related Articles

• Website Rebuild & Patch Notes

  After months of planning and development, I'm excited to share the fully rebuilt version of my website. This update marks a major shift in both design and architecture — moving away from the legacy ASP.NET Core 2.1 MVC framework to a modern .NET 8 Blazor Web App, combining both Blazor Server and WebAssembly. In this post, I’ll highlight the

  2025-03-24 15:32:25 JST | Web | 158 reads
• 在a标签里面增加rel="noopener noreferrer"有什么用?

  简单来讲，这样做是为了防止钓鱼网站。你的页面如果不加上这个rel="noopener"会被人链接到别的网站，原理：

  2020-01-22 08:03:25 JST | Web | 3k reads
• How to do blog donation function?

  About CSS: The total number of images replaced is 3, which are quotation marks, radio1 and radio2 images The. Content class may conflict with your CSS. It is necessary to modify your style About JavaScript: No change required

  2020-07-03 00:57:07 JST | Web | 2k reads
• 博客打赏功能制作（附源码）及详细说明

  关于CSS： 图片替换总数为3张，分别为引号、radio1、radio2图片 .content类可能与你的CSS冲突，有必要修改你的样式 关于JavaScript: 无需改动 关于HTML： alipay.jpg\wechat.jpg\alipayimg.png\wechatimg.png\close.jpg 要准备好 注意裁剪二维码，大小为140*140px

  2020-06-13 18:23:18 JST | Web | 2k reads
• Why not recommend you to use Blogger in 2020 (Specially for programmers)

  As a programmer, I recommend that you write a blog yourself instead of using blogger. A few days ago, I used Blogger and I found its editor very difficult to use. Because I am a programmer, I need to paste the code, but the display of the code in Blogger is very bad. For example, the style I thought would work, but it didn't work on Blogger. I think the CSS style has been overwritten. So I opened

  2020-12-14 16:46:06 JST | Web | 2k reads
• 仿CSDN侧边栏滚轮响应脚本

  这是本网站使用的，仿CSDN侧边栏滚轮响应脚本，需要先引入Jquery配合使用

  2020-01-24 22:01:37 JST | Web | 1k reads