Google Ads API では、YouTube 動画を Google 広告アカウントにリンクできます。このガイドでは、API を使用してアカウントへのリンクを追加、削除する方法について説明します。
動画をリンク
動画をアカウントにリンクするには、次の 2 つの方法があります。どちらの方法を使用するかは、プロセスを開始するユーザーによって異なります。
- 動画をアカウントにリンクするようリクエストします。このシナリオでは、クリエイターにリクエストを送信し、クリエイターがそのリクエストを承認することで、動画へのリンクが確立されます。延長されたリクエストは、承認される前であれば取り消すことができます。また、リンクされた動画は、承認された後でも削除できます。
- 動画のクリエイターが、動画を Google 広告アカウントにリンクするようリクエストしています。リクエストを承認するか拒否するかを選択できます。
各シナリオでは、次のメソッドが使用されます。
| シナリオ | アクション | 備考 |
|---|---|---|
| シナリオ 1 | YouTube API から動画情報を取得する | YouTube API を使用して、動画リンク リクエストの送信先となる channel_id と、リンクする動画の video_id を取得します。video_id は、YouTube 動画の URL に含まれる 11 文字の文字列です（例: www.youtube.com/watch?v=VIDEO_ID の v パラメータ、youtu.be/VIDEO_ID のパス）。 |
| リンク リクエストを作成 |
DataLinkService.CreateDataLink メソッドを使用してリンク リクエストを作成し、youtube_video.channel_id と youtube_video.video_id の両方を指定して動画とそれに関連付けられたチャンネルを識別します。v24 以降では、youtube_link_metadata.brand_channel_id を指定して、リンクされた YouTube ブランド チャンネルの ID を提供し、クリエイターがブランドを理解できるようにすることもできます。DataLink の status は設定しないでください。API 呼び出しが正常に完了すると、Google Ads API サーバーによって REQUESTED に設定されます。 |
|
| リクエストのステータスを調べる | GoogleAdsService.SearchStream または GoogleAdsService.Search を使用して data_link リソースをクエリし、その
status を確認します。 |
|
| リクエストを取り消す |
DataLinkService.UpdateDataLink メソッドを使用して、
DataLink の status を REQUESTED から REVOKED に変更することで、リンク リクエストを取り消します。 |
|
| リンクを削除する | リンクされた動画を削除するには、
DataLinkService.RemoveDataLink を使用します。 |
|
| シナリオ 2 | 招待状を取得する | GoogleAdsService.Search または GoogleAdsService.SearchStream を使用して、data_link リソースをクエリします。
status = PENDING_APPROVAL でフィルタして、承認または拒否するリンク リクエストを見つけます。 |
| リンク リクエストを承認または拒否する |
DataLinkService.UpdateDataLink メソッドを使用して、DataLink のステータスを ENABLED（リクエストを承認する場合）または REJECTED（リクエストを拒否する場合）に更新します。 |
リンクの詳細を取得する
GoogleAdsService.Search または GoogleAdsService.SearchStream を使用して、data_link リソースをクエリできます。次のクエリは、YouTube 動画 ID やチャンネル ID など、YouTube 動画リンクの詳細を取得します。
SELECT
data_link.resource_name,
data_link.status,
data_link.youtube_video.video_id,
data_link.youtube_video.channel_id
FROM data_link
WHERE data_link.type = 'VIDEO'
このワークフローでは、次の一般的なエラーがスローされる可能性があります。
| エラーコード | 説明 |
|---|---|
DataLinkError.PERMISSION_DENIED |
お客様には、この操作を行う権限がありません。 |
DataLinkError.YOUTUBE_VIDEO_ID_INVALID |
動画 ID が無効なため、動画リンクを作成できませんでした。 |
DataLinkError.INVALID_STATUS |
リクエストされたオペレーションに対してデータリンクの現在のステータスが無効な場合にスローされます。 |
DataLinkError.INVALID_UPDATE_STATUS |
更新中にサポートされていないステータス遷移を試みた場合にスローされます（例: REVOKED から ENABLED に直接移動する）。 |
MutateError.RESOURCE_ALREADY_EXISTS |
動画のデータリンクがすでに存在する場合にスローされます。 |