スタートガイド

クリエイティブアセット管理を実装する方法について詳細をご確認ください。

要件

このAPIを使用するには、以下が必要です。

• MetaアプリID
• ビジネスマネージャID
• Facebookログインを実装する

アクセス許可

アプリにログインしたら、ユーザーに次のアクセス許可を要求する必要があります。

• business_creative_management - ビジネスクリエイティブフォルダーとビジネスクリエイティブを管理します。すべてのビジネスクリエイティブアセットマネージャAPIエンドポイントで必須。
• business_creative_insights - ビジネスクリエイティブアセットインサイトにアクセスします。
• business_management - ビジネスユーザーを管理し、パートナーシップ契約のリクエストを受け入れます。

制限

• アプリユーザー(広告主)は、ビジネスマネージャIDで表されるビジネスの管理者である必要があります

ステップ1: ビジネスクリエイティブフォルダーを作成する

{business-id}/creative_foldersエンドポイントに対してPOSTリクエストを発行することにより、広告主のビジネスのためのビジネスクリエイティブフォルダーを作成します。この場合、{business-id}は広告主のビジネスIDです。

このアクションにはbusiness_creative_managementのアクセス許可が必要です。

リクエストの例

curl -X POST \
  -F 'name={folder-name}' \
  -F 'access_token={access-token}' \
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders

応答の例

{ “id”: “{business-creative-folder-id}” }

サブフォルダーを作成することもできます。

ステップ2: フォルダーにクリエイティブを追加する

{business-id}/imagesまたは{business-id}/videosにPOSTリクエストを発行することにより、既存のクリエイティブアセットをフォルダーに追加します。このアクションには、business_creative_managementアクセス権限が必要です。

画像の追加

例 — 画像を追加するには、次のようにします。

curl -X POST \
  -F 'bytes={image-content-in-bytes-format}' \
  -F 'name={image-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  https://graph.facebook.com/{version}/{business-id}/images

応答

{
  "images":{
    "{image-name}":{
      "id":"{business-image-id}",
      "hash":"{hash}",
      "url":"{image-url}"
    }
  }
}

動画のアップロード

数メガバイト以下の動画の場合は、1回のリクエストでアップロードします。それ以上の場合は、分割してアップロードします。動画アップロードのAPI呼び出しは、graph.facebook.comではなく、graph-video.facebook.comで発行します。

例 — {business-id}/videoにPOSTを送信します。その際に、動画の名前、ソース、ビジネスクリエイティブフォルダーIDを含めます。

curl -X POST \
  -F 'name={video-name}' \
  -F 'source='@{video-path}'' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  https://graph-video.facebook.com/{version}/{business-id}/videos

応答

{ 
    "success": true, 
    "business_video_id": "{business-video-id}" 
}

動画の分割アップロード

大きな動画の場合は、1つのstartリクエスト、1つまたは複数のtransferリクエスト、1つのfinishリクエストを送信します。

startリクエストを発行し動画アップロードセッションを作成するには、/{business-id}/videosにPOSTリクエストを送信します。その際に、upload_phaseフィールドをstartに設定し、file_sizeにバイト数を指定します。

curl -X POST \
  -F 'title={video-name}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'access_token={access-token}' \
  -F 'upload_phase=start' \
  -F 'file_size={video_file_size_in_bytes}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

応答の例

{
  "upload_session_id": "{session-id}",
  "business_video_id": "{business-video-id}",
  "video_id": "{video-id}",
  "start_offset": "0",
  "end_offset": "52428800"
}

動画の[0, 52428800]をアップロードするには、開始オフセットと終了オフセットに従ってファイルをチャンクに分割してから、transferリクエストでそれぞれのチャンクを送信します。チャンクごとに新しいオフセットが送られてきます。それらの新しいオフセットを使うことにより、各チャンクをアップロードします。

例: 最初のチャンクを送信する

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=transfer' \
  -F 'upload_session_id={session-id}' \
  -F 'start_offset=0' \
  -F 'video_file_chunk=@{binary-chunk-filename}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

成功すると、次のチャンクのオフセットが応答として返されます。

{
 "start_offset": "52428800",    //Start byte position of the next file chunk.
 "end_offset": "104857601"      //End byte position of the next file chunk.
}

ファイルのうち[52428800, 104857601]を範囲としてカットして2番目のチャンクとしてアップロードし、送信します。

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=transfer' \
  -F 'start_offset=52428801' \
  -F 'upload_session_id={your-upload-sesson-id}' \
  -F 'video_file_chunk={binary-chunk-filename}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

start_offsetとend_offsetが等しくなるまで、追加のチャンクをすべて送信します。

{
  "start_offset": "152043520",
  "end_offset": "152043520"
}

それらが等しいことは、ファイル全体がアップロードされたことを意味します。次に、この動画を投稿し、アップロードセッションを閉じる必要があります。

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=finish' \
  -F 'upload_session_id={session-id}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

アップロード中にエラーが発生した場合、そのチャンクのアップロードを再試行することができます。通常、エラーは応答の問題に起因します。失敗したチャンクのアップロードを再試行してください。エラーについて詳しくは、次をご覧ください。

• 再開可能なアップロードエラー
• グラフAPIの使用、エラーの処理

クリエイティブをフォルダーにアップロードすると、そのフォルダーにアクセスできる広告主は、広告マネージャまたはマーケティングAPIのいずれかにより広告を作成できます。

アップロードされたクリエイティブすべてが、[広告マネージャ] > [メディア選択]のUIに表示されます。それらを広告作成と広告編集で使うことができます。さらに、フォルダーとクリエイティブアセットは、[ビジネスマネージャ] > [メディアライブラリ]の中のビジネスマネージャメディアツールでも利用可能です。

ステップ3: アセットへのディープリンクURLを提供し、広告または投稿を作成する

特定のアセットのディープリンクURLを取得するには、アップロードされた画像または動画のアセットのmedia_library_urlフィールドをクエリします。

curl -X GET \  
  -F 'access_token={partner-access-token}' \
https://graph.facebook.com/v<API_VERSION>/<asset_id>?fields=media_library_url

ディープリンクを使って広告またはページ投稿を作成するには、リンクの末尾に&action=CREATE_ADまたは&action=CREATE_POSTを付加します。

https://business.facebook.com/asset_library/business_creatives/?object_id=<OBJECT_ID>&action=CREATE_AD