# Facebook 広告への接続
Facebook 広告は、あらゆる規模の企業がターゲットオーディエンスに到達し、さまざまなマーケティング目標を達成するために使用する強力なデジタル広告プラットフォームです。このプラットフォームにより、広告主は、Facebook や Messenger などのFacebook のアプリやサービス群全体で表示できるカスタマイズされた広告を作成できます。Facebook 広告は高度なターゲティング機能を備えているため、企業は特定のターゲット層、関心、行動、場所にまでリーチすることができます。
**Topics**
+ [AWS Glue による Facebook 広告のサポート](facebook-ads-support.md)
+ [接続を作成および使用するための API オペレーションを含むポリシー](facebook-ads-configuring-iam-permissions.md)
+ [Facebook 広告の設定](facebook-ads-configuring.md)
+ [Facebook 広告接続の設定](facebook-ads-configuring-connections.md)
+ [Facebook 広告エンティティからの読み取り](facebook-ads-reading-from-entities.md)
+ [Facebook 広告の接続オプション](facebook-ads-connection-options.md)
+ [Facebook 広告コネクタの制限と注意事項](facebook-ads-connector-limitations.md)
# AWS Glue による Facebook 広告のサポート
AWS Glue は、次のように Facebook 広告をサポートします:
**ソースとしてサポートされていますか?**
はい。AWS Glue ETL ジョブを使用して、Facebook 広告からデータをクエリできます。
**ターゲットとしてサポートされていますか?**
いいえ。
**サポートされている Facebook Ads API バージョン**
以下の Facebook Ads API バージョンがサポートされています:
+ v17.0
+ v18.0
+ v19.0
+ v20.0
# 接続を作成および使用するための API オペレーションを含むポリシー
次のサンプル ポリシーで、接続の作成と使用に必要な AWS IAM 権限について説明します。新しいロールを作成する場合は、以下を含むポリシーを作成します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"glue:ListConnectionTypes",
"glue:DescribeConnectionType",
"glue:RefreshOAuth2Tokens",
"glue:ListEntities",
"glue:DescribeEntity"
],
"Resource": "*"
}
]
}
```
------
上記の方法を使用しない場合は、代わりに次のマネージド IAM ポリシーを使用します:
+ [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – さまざまな AWS Glue プロセスを実行するために必要なリソースへのアクセス権をユーザーに代わって付与します。これらのリソースには AWS Glue 、Amazon S3、IAM、CloudWatch Logs、および Amazon EC2 が含まれます。このポリシーで指定されたリソースの命名規則に従った場合、AWS Glue プロセスは必要なアクセス権限を使用できます。このポリシーは、通常、クローラ、ジョブ、開発エンドポイントを定義するときに指定されたロールにアタッチされます。
+ [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess) — ポリシーがアタッチされているアイデンティティが AWS マネージメントコンソールを使用するときは、AWS Glue リソースへのフルアクセスを許可します。このポリシーで指定されたリソースの命名規則に従った場合、ユーザーは完全なコンソール機能を使用できます。このポリシーは、通常 AWS Glue コンソールのユーザーにアタッチされています。
# Facebook 広告の設定
AWS Glue を使用して Facebook 広告からデータを転送できるようにするには、次の要件を満たす必要があります:
## 最小要件
以下に、最小要件を示します。
+ Facebook スタンダードアカウントは Facebook から直接アクセスできること。
+ アクセストークンを生成するには、ユーザー認証が必要です。
+ Facebook 広告の SDK コネクタは、*ユーザーアクセストークン OAuth *フローを実装すること。
+ Facebook 広告への API リクエストの認証には OAuth2.0 を使用すること。このウェブベースの認証は、2FA 上位セットである多要素認証 (MFA) アーキテクチャに該当します。
+ ユーザーは、エンドポイントにアクセスするためのアクセス許可を付与する必要があります。ユーザーのデータにアクセスするために、エンドポイント認可は[アクセス許可](https://developers.facebook.com/docs/permissions)と[機能](https://developers.facebook.com/docs/features-reference)を通じて処理されます。
## OAuth 2.0 認証情報の取得
API 認証情報を取得してインスタンスに対して認証呼び出しを行うには、Facebook 広告デベロッパーガイドの「[REST API](https://developers.facebook-ads.com/rest-api/)」を参照してください。
# Facebook 広告接続の設定
Facebook 広告は、OAuth2 の AUTHORIZATION\$1CODE のグラントタイプをサポートしています。
+ このグラントタイプは、ユーザーを認証するためにサードパーティーの認証サーバーにユーザーをリダイレクトすることから、three-legged の OAuth と見なされます。AWS Glue コンソール経由で接続を作成するときに使用されます。
+ ユーザーは、Facebook 広告で独自の接続アプリを作成し、AWS Glue コンソールを介して接続を作成するときに独自のクライアント ID とクライアントシークレットを指定することを選択できます。このシナリオでは、引き続き Facebook 広告にリダイレクトされてログインし、リソースへアクセスするために AWS Glue を承認します。
+ このグラントタイプは、アクセストークンになります。期限切れのシステムユーザートークンは、生成または更新された日付から 60 日間有効です。継続性を作成するには、開発者は 60 日以内にアクセストークンを更新する必要があります。そうしないと、アクセストークンは失われ、開発者は API アクセスを回復するために新しいトークンを取得する必要があります。「[Refresh Access Token](https://developers.facebook.com/docs/marketing-api/system-users/install-apps-and-generate-tokens/)」を参照してください。
+ 認可コード OAuth フロー用の接続アプリの作成に関する Facebook 広告の公開ドキュメントについては、Google の開発者向けガイドの「[OAuth 2.0 を使用した Google API へのアクセス](https://developers.google.com/identity/protocols/oauth2)」を参照してください。
Facebook 広告接続を設定するには:
1. AWS Glue Glue Studio で、以下の手順に従って **[データ接続]** の下に接続を作成します。
1. **[接続タイプ]** を選択する際に、[Facebook 広告] を選択します。
1. 接続先の Facebook 広告インスタンスの `INSTANCE_URL` を指定します。
1. AWS Glue が次のアクションを引き受けて、その権限を持つことができる AWS IAM ロールを選択します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
------
1. AWS Glue でこの接続に使用する `secretName` を選択して、トークンを配置します。
1. ネットワークを使用する場合は、ネットワークオプションを選択します。
1. AWS Glue ジョブに関連付けられている IAM ロールに `secretName` を読み取るアクセス許可を付与します。
# Facebook 広告エンティティからの読み取り
**前提条件**
読み取り元の Facebook 広告オブジェクト。オブジェクト名が必要になります。次の表は、サポートされているエンティティを示しています。
**ソースに対応するエンティティ**:
| エンティティ | フィルタリング可能 | 制限をサポートする | Order By をサポートする | Select \$1 をサポートする | パーティション分割をサポートする |
| --- | --- | --- | --- | --- | --- |
| キャンペーン | はい | あり | なし | あり | あり |
| Ad Set | はい | あり | なし | あり | あり |
| Ads | はい | あり | なし | あり | あり |
| Ad Creative | なし | あり | なし | あり | なし |
| Insights - Account | なし | あり | なし | あり | なし |
| Adaccounts | はい | あり | なし | あり | なし |
| Insights - Ad | はい | あり | なし | あり | あり |
| Insights - AdSet | はい | あり | なし | あり | あり |
| Insights - Campaign | はい | あり | なし | あり | あり |
**例**:
```
FacebookAds_read = glueContext.create_dynamic_frame.from_options(
connection_type="FacebookAds",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v20.0"
}
```
## Facebook 広告エンティティとフィールドの詳細
エンティティとフィールドの詳細については、以下を参照してください:
+ [Ad Account](https://developers.facebook.com/docs/marketing-api/reference/ad-account)
+ [Campaign](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group)
+ [Ad Set](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign)
+ [Ad](https://developers.facebook.com/docs/marketing-api/reference/adgroup)
+ [Ad Creative](https://developers.facebook.com/docs/marketing-api/reference/ad-creative)
+ [Insight 広告アカウント](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights)
+ [Insights 広告](https://developers.facebook.com/docs/marketing-api/reference/adgroup/insights/)
+ [Insights AdSets](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/insights)
+ [Insights キャンペーン](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group/insights)
詳細については、「[Marketing API](https://developers.facebook.com/docs/marketing-api/reference/v21.0)」を参照してください。
**注記**
構造体データ型とリストデータ型は、コネクタの応答で文字列データ型に変換されます。
## パーティショニングクエリ
Spark で同時実行を使用する場合は、追加の Spark オプション `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、および `NUM_PARTITIONS` を指定できます。これらのパラメータを使用すると、元のクエリは Spark タスクで同時に実行できるサブクエリの `NUM_PARTITIONS` の数に分割されます。
+ `PARTITION_FIELD`: クエリのパーティション化に使用するフィールドの名前。
+ `LOWER_BOUND`: 選択したパーティションフィールドの**包括的な**下限値。
DateTime フィールドでは、Spark SQL クエリで使用される Spark タイムスタンプ形式を受け入れます。
有効な値の例:
```
"2022-01-01"
```
+ `UPPER_BOUND`: 選択したパーティションフィールドの**排他的**上限値。
+ `NUM_PARTITIONS`: パーティション数。
例:
```
FacebookADs_read = glueContext.create_dynamic_frame.from_options(
connection_type="FacebookAds",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v20.0",
"PARTITION_FIELD": "created_time"
"LOWER_BOUND": "2022-01-01"
"UPPER_BOUND": "2024-01-02"
"NUM_PARTITIONS": "10"
}
```
# Facebook 広告の接続オプション
Facebook 広告の接続オプションは次のとおりです:
+ `ENTITY_NAME`(文字列) – (必須) 読み取りに使用されます。Facebook 広告内のオブジェクトの名前。
+ `API_VERSION`(文字列) – (必須) 読み取りに使用されます。使用する Facebook 広告 Rest API バージョン。例: v1。
+ `SELECTED_FIELDS`(List) – Default: empty(SELECT \$1). 読み込みに使用されます。オブジェクトに選択する列です。
+ `FILTER_PREDICATE`(文字列) – デフォルト: 空 読み込みに使用されます。Spark SQL 形式である必要があります。
+ `QUERY`(文字列) - デフォルト: 空 読み込みに使用されます。完全な Spark SQL クエリです。
+ `PARTITION_FIELD` (文字列) – 読み取りに使用されます。クエリをパーティション化するために使用するフィールドです。
+ `LOWER_BOUND` (文字列)– 読み取りに使用されます。選択したパーティションフィールドの包括的な下限値。
+ `UPPER_BOUND` (文字列) – 読み取りに使用されます。選択したパーティションフィールドの排他的上限値。
+ `NUM_PARTITIONS`(整数) – デフォルト: 1。読み込みに使用されます。読み取り用のパーティションの数です。
+ `TRANSFER_MODE` (文字列) – デフォルト: SYNC。非同期読み取りに使用されます。
# Facebook 広告コネクタの制限と注意事項
Facebook 広告コネクタの制限事項または注意事項は次のとおりです:
+ Facebook 広告は動的メタデータをサポートしているため、すべてのフィールドをクエリできます。すべてのフィールドがフィルタリングをサポートしており、データが利用可能な場合はレコードが取得されます。それ以外の場合、Facebook は適切なエラーメッセージとともに Bad リクエスト (400) レスポンスを返します。
+ アプリの呼び出し回数は、1 時間のウィンドウ 200 中にユーザーが実行できる呼び出しの回数に、ユーザー数を掛けたものです。レート制限の詳細については、「[Rate Limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/)」と「[Business Use Case Rate Limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#buc-rate-limits)」を参照してください。