YouTube APIキー（YouTube Data API v3）の取得と初回リクエストの作成方法

YouTube APIキーは、コードが公開されているYouTubeデータを読み取るための認証情報です。具体的には、動画の詳細、チャンネル統計、検索結果、プレイリストの内容などです。Googleのドキュメントには、「OAuth 2.0トークンを提供しないリクエストはAPIキーを送信する必要があります。キーはプロジェクトを識別し、APIアクセス、クォータ、レポートを提供します」と明記されています。キーがなければ、データは取得できません。

このガイドでは、何もないGoogle Cloudプロジェクトから、約15分で動作するリクエストを作成するまでの手順を説明します。まず、YouTube Data API v3を有効にし、キーを作成して保護し、curlとPythonからAPIを呼び出し、その後Apidogにキーを保存してリクエストを繰り返し可能なテストとして保存します。最初に全体像を把握したい場合は、YouTube Data APIの概要でAPIが提供する内容を説明しています。この投稿は実践的な部分です。

ボタン

始める前に必要なもの

Googleアカウント。これはCloud Consoleを開いてプロジェクトを作成するために十分です。
コードサンプル用のcurl（macOSとほとんどのLinuxディストリビューションに付属）とrequestsパッケージを含むPython 3。
キーをシークレットとして保存し、リクエストをテストとして保存したい場合はApidog。無料プランでここにあるすべてをカバーできます。

ステップ1：Google Cloudプロジェクトを作成する

Google Cloud Consoleを開いてサインインします。ページ上部のプロジェクト選択ツールを使用して、新しいプロジェクト（例: youtube-integration）を作成します。後で表示されるすべてのAPIキー、クォータバケット、使用状況レポートは、このプロジェクトにスコープされるため、無関係なツール間でキーを共有するのではなく、アプリごとに1つのプロジェクトを保持してください。アプリにすでにプロジェクトがある場合は、それを使用します。

ステップ2：YouTube Data API v3を有効にする

新しいプロジェクトでは、APIはデフォルトで無効になっています。コンソールで「APIとサービス」に移動し、「APIライブラリ」を開き、「YouTube Data API v3」を検索して有効にします。Googleのスタートガイドでは、別の方法で同じ確認を説明しています。「有効なAPI」ページにアクセスし、リストにない場合はAPIを有効にします。

この手順をスキップすると、最初のリクエストは403エラーで失敗し、「プロジェクトでAPIが使用されていないか、無効になっています」と表示されます。これは、新品のキーが「機能しない」最も一般的な理由です。

ステップ3：APIキーを作成する

「APIとサービス」に移動し、次に「認証情報」に移動します。「認証情報を作成」をクリックし、「APIキー」を選択します。コンソールはすぐにキーを生成し、ダイアログに表示します。安全な場所にコピーしてください。

キーはパスワードのように扱ってください。Gitリポジトリ、Slackスレッド、またはクライアントサイドのJavaScriptバンドルに貼り付けないでください。すでにコミットされてしまった場合は、公開されたAPIキーの発見と修正に関するガイドで、そのクリーンアップ方法を説明しています。

ステップ4：キーを制限する

Google自身のドキュメントには、「無制限のAPIキーは安全ではありません」と記載されています。作成直後に「キーを制限」をクリックします。Cloud APIキーガイドに記載されている2つの独立した制御があります。

アプリケーションの制限：誰がキーを提示できるかを決定します。次のいずれかを選択します。ウェブサイト（HTTPリファラー、限定的なワイルドカードサポート）、IPアドレス（IPv4、IPv6、またはCIDR範囲）、Androidアプリ（パッケージ名とSHA-1証明書フィンガープリント）、またはiOSアプリ（バンドルID）。バックエンドサービスはIPアドレスを使用すべきです。ブラウザ専用のウィジェットはリファラーを使用すべきです。
APIの制限：キーが呼び出せるAPIを決定します。「キーを制限」を選択し、YouTube Data API v3のみを選択します。キーが漏洩した場合、攻撃者はYouTubeのクォータのみを取得し、他には何も得られません。

テストする前に、保存して変更が有効になるまで数分待ちます。同じガイドからのもう2つの習慣：侵害されたキーによる損害を制限するために、定期的にキーをローテーションし、すべての呼び出し元が新しいキーに移行したら古いキーを削除します。次のステップでの注意点：IPアドレスでサーバーに制限をかけた場合、ラップトップからのcurlはブロックされるため、許可されたホストからテストするか、別の開発キーを作成してください。

ステップ5：curlとPythonで最初のリクエストを作成する

すべてのエンドポイントはhttps://www.googleapis.com/youtube/v3/の下にあります。キーはkeyクエリパラメータとして渡すか（Googleの例もこの方法を使用）、x-goog-api-keyヘッダーに入れてURLやアクセスログから保護します。どちらの方法もライブAPIで機能します。

最も安価で便利な呼び出しであるvideos.listから始めましょう。これは1つまたは複数の動画IDの詳細を返し、1クォータユニットを消費します。以下のIDは、Googleがドキュメントで使用しているものです。

export YOUTUBE_API_KEY="AIza...your-key..."

curl -s "https://www.googleapis.com/youtube/v3/videos?part=snippet,statistics&id=7lCDEYXw3mM" \
  -H "x-goog-api-key: $YOUTUBE_API_KEY"

省略されたレスポンスは次のようになります。

{
  "kind": "youtube#videoListResponse",
  "items": [
    {
      "id": "7lCDEYXw3mM",
      "snippet": { "title": "...", "channelTitle": "...", "publishedAt": "..." },
      "statistics": { "viewCount": "...", "likeCount": "..." }
    }
  ]
}

partパラメータは必須で、どのセクションを返すかを制御します。snippet、statistics、contentDetails、statusが最もよく使用されるものです。

次に、多くの人が求める検索です。requestsを使ったPythonでの例です。

import os
import requests

API_KEY = os.environ["YOUTUBE_API_KEY"]
BASE = "https://www.googleapis.com/youtube/v3"

resp = requests.get(
    f"{BASE}/search",
    params={"part": "snippet", "q": "api testing", "type": "video", "maxResults": 10},
    headers={"x-goog-api-key": API_KEY},
    timeout=10,
)

if resp.status_code != 200:
    err = resp.json()["error"]
    raise SystemExit(f"{err['code']} {err['errors'][0]['reason']}: {err['message']}")

for item in resp.json()["items"]:
    print(item["id"]["videoId"], item["snippet"]["title"])

search.listの場合、partはsnippetでなければならず、maxResultsはデフォルトで5（0から50まで許容）であり、typeはデフォルトでvideo,channel,playlistなので、動画のみが必要な場合はvideoに設定します。検索結果はトップレベルではなくid内にvideoIdを持つため、上記のループではitem["id"]["videoId"]と読み取ります。

ステップ6：キーを保存し、Apidogでリクエストを実行する

シェル変数では1つのスクリプトに対して機能しますが、チームでは機能せず、保存された再実行可能なチェックも提供されません。以下に、クラウドからキーを離してApidogで同じリクエストを行う方法を示します。

環境を作成します。 YouTubeという名前の環境を、base_urlをhttps://www.googleapis.com/youtube/v3に設定し、youtube_api_keyという2つの変数とともに作成します。キーについては、共有値をプレースホルダーのままにし、実際のキーをローカル値フィールドに貼り付けます。ローカル値はクライアントのキャッシュに残り、チームメイトと同期されることはありません。詳細な設定は、Apidogの環境とシークレット変数に関するガイドに記載されています。
リクエストを作成します。 新しいリクエストで、GET {{base_url}}/videos、クエリパラメータpart=snippet,statisticsとid=7lCDEYXw3mM、そしてヘッダーx-goog-api-keyを{{youtube_api_key}}に設定します。YouTube環境を選択して送信します。curl呼び出しと同じJSONが表示されるはずです。
テストに変換します。 リクエストのポストプロセッサーで、アサーションを追加します。ステータスが200と等しいこと、そして$.items[0].idが7lCDEYXw3mMと等しいことを確認します。リクエストを保存し、テストシナリオに追加します。このチェックは、オンデマンドで、スケジュールで、またはApidog CLIを通じてCIで実行できるようになります。CLIでは、--env-var "youtube_api_key=$YOUTUBE_API_KEY"によって、キーが保存される代わりに実行時に挿入されます。

キーがローテーションされたり、制限が変更されたりしたときに、そのメリットが初めてわかります。1つのシナリオを再実行するだけで、すべてのYouTube呼び出しがまだ機能しているかどうかを数秒で確認できます。Apidogをダウンロードして一緒に試してみてください。4人までのチームは無料で利用できます。

クォータと制限

YouTube Data APIはドルで請求されるのではなく、クォータユニットで請求され、その数値はGoogleのクォータ計算ページから取得されます。APIを有効にしたすべてのプロジェクトは、次のデフォルト割り当てを受けます。

バケット	1日あたりのデフォルト	呼び出しあたりのコスト
`search.list`	100回	1ユニット（独自のバケット）
`videos.insert`	100回	1ユニット（独自のバケット）
その他のすべてのエンドポイント合計	10,000ユニット	変動、下記参照

共有の10,000ユニットのプール内では、videos.list、channels.list、playlistItems.list、commentThreads.listなどのリストメソッドはそれぞれ1ユニットを消費します。書き込みはさらにコストがかかります。videos.updateとvideos.deleteは50ユニット、captions.insertは400ユニットです。同じページには、これに基づいて設計する方法を形作る4つのルールがあります。

クォータは太平洋時間の深夜にリセットされます。
無効なリクエストを含むすべてのリクエストは、少なくとも1ユニットを消費します。不正な呼び出しを再試行するループは、無駄にクォータを消費します。
ページ分割された結果の追加ページは、最初のページと同じコストがかかります。
デフォルトの割り当ては「変更される可能性があります」。キャパシティを計画する前に、チュートリアルではなくページを確認してください。

古いガイドでは、検索を10,000プールから100ユニットと評価していました。現在のページではsearch.listが独自のバケットに入れられているため、上限は依然として1日あたり100回の検索ですが、検索が他の呼び出しのクォータを消費することはなくなりました。

それでも不十分な場合は、クォータとコンプライアンス監査ページからYouTube API Services Audit and Quota Extension Formを参照してください。提出する前に、レスポンスをキャッシュし、必要なpart値のみをリクエストし、IDを1つのvideos.list呼び出しにバッチ処理してください（idパラメータはカンマ区切りのリストを受け取ります）。使用状況はCloud Consoleの「クォータ」ページに表示されます。

よくあるエラーとその修正方法

Googleのエラーリファレンスには、API独自のエラーコードが記載されています。以下の最初の2行は、不正なキーまたはキーなしでライブAPIに実際のリクエストを送信した結果です。

HTTP	理由	表示されるメッセージ	修正
400	`badRequest` (`API_KEY_INVALID`)	「APIキーが有効ではありません。有効なAPIキーを渡してください。」	入力ミス、削除されたキー、またはYouTube Data API v3を除外するAPI制限。キーを再作成または編集してください。
403	`forbidden`	「メソッドは未登録の呼び出し元を許可しません…」	キーが送信されていません。`key`パラメータまたは`x-goog-api-key`ヘッダーを追加してください。
403	`quotaExceeded`	「クォータを超過したため、リクエストを完了できません。」	太平洋時間の深夜リセットを待つか、冗長な呼び出しを削減するか、拡張をリクエストしてください。
400	`missingRequiredParameter`	「リクエストに必要なパラメータがありません。」	ほとんどの場合、`part`の欠落です。
401	`authorizationRequired`	「リクエストは`mine`パラメータを使用していますが、適切に認証されていません。」	この呼び出しにはAPIキーではなくOAuth 2.0トークンが必要です。FAQを参照してください。

実践からのもう一つ：アプリケーションの制限が呼び出し元と一致しない場合、ブロックされたリファラーまたはIPを示す403エラーが発生します。制限を修正するか、許可されたホストから呼び出してください。また、古いフォーラムスレッドでは無効なキーエラーをkeyInvalidと呼んでいますが、ライブAPIはAPI_KEY_INVALIDの詳細を含むbadRequestを返しますので、レガシーな理由文字列ではなく、メッセージまたは詳細で一致させてください。

よくある質問

YouTube APIキーは無料ですか？

はい。キーの作成に費用はかかりません。ドキュメントにはAPIの料金が金銭ではなくクォータユニットで記載されています。上記のデフォルトの割り当ては、何も要求しなくても取得できるものです。

APIキーの代わりにOAuthが必要になるのはどのような場合ですか？

APIキーはプロジェクトを識別し、公開データをロック解除します。個人のユーザーデータに触れたり、何かを挿入、更新、削除したりする瞬間に、Googleはそのデータの所有者であるユーザーからのOAuth 2.0トークンを要求します。動画の評価、自身の登録チャンネルのリスト表示、またはmine=trueフィルターの使用はすべてOAuth側で行われます。APIキーとベアラートークンの比較では、2つの認証情報が異なる質問に答える理由を説明します。

AIエージェントは私のYouTube APIキーを使用できますか？

はい、キーの制限が許可する場所でエージェントが実行される限り可能です。YouTube MCPサーバーは、動画データをコーディングアシスタントに渡すための一つの方法です。Data APIとそれが動作するマシンに制限されたキーを与え、プロンプト自体には含めないようにします。

キーが漏洩した場合、どうすればよいですか？

「認証情報」ページでキーを削除し、新しいキーを作成します。その後、漏洩元を修正します。キーをApidogのローカル値またはシークレットストアに移動し、古いキーが履歴に残っていないかリポジトリをスキャンします。

次のステップ

これで、プロジェクト、有効化されたAPI、制限されたキー、そしてcurl、Python、Apidogから機能するリクエストが揃いました。保存されたシナリオをCIに組み込み、最適化の時期を「クォータ」ページで確認してください。