本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 連線至 Instagram Ads Instagram 是熱門的相片分享應用程式，可讓您與品牌、名人、思維領導者、朋友、家人等聯繫。其是一種相片分享和社交聯網服務。使用者可以拍攝相片或短片，並與其追隨者分享。Instagram 廣告是企業可以付費為 Instagram 使用者提供服務的貼文。 **Topics** + [AWS Glue 支援 Instagram 廣告](instagram-ads-support.md) + [包含用於建立和使用連線的 API 操作的政策](instagram-ads-configuring-iam-permissions.md) + [設定 Instagram Ads](instagram-ads-configuring.md) + [設定 Instagram Ads 連線](instagram-ads-configuring-connections.md) + [從 Instagram Ads 實體中讀取](instagram-ads-reading-from-entities.md) + [Instagram Ads 連線選項](instagram-ads-connection-options.md) + [Instagram Ads 連接器的限制和備註](instagram-ads-connector-limitations.md) # AWS Glue 支援 Instagram 廣告 AWS Glue 支援 Instagram 廣告，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Instagram Ads 查詢資料。 **支援作為目標？** 否。 **支援的 Instagram Ads API 版本** 支援以下 Instagram 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 主控台的使用者。 # 設定 Instagram Ads 您必須先符合下列要求，才能使用 從 Instagram 廣告 AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 可以透過 Facebook 間接存取 Instagram Standard 帳戶。 + 需要使用者身分驗證才能產生存取字符。 + Instagram Ads SDK 連接器將實作*使用者存取字符 OAuth* 流程。 + 我們使用 OAuth2.0 來驗證對 Instagram Ads 的 API 請求。此 Web 型身分驗證屬於多重要素驗證 (MFA) 架構，其是 2FA 的超集。 + 使用者需要授權許可，才能存取端點。為了存取使用者的資料，可透過[許可](https://developers.facebook.com/docs/permissions)和[功能](https://developers.facebook.com/docs/features-reference)來處理端點授權。 ## 取得 OAuth 2.0 憑證 若要取得 API 憑證，以便對執行個體進行已驗證的呼叫，請參閱 [Graph API](https://developers.facebook.com/docs/graph-api/)。 # 設定 Instagram Ads 連線 Instagram Ads 支援 OAuth2 的 AUTHORIZATION\$1CODE 授權類型。 + 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。 + 使用者可以選擇在 Instagram Ads 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 Instagram 廣告以登入並授權 AWS Glue 存取其資源。 + 此授權類型會產生存取字符。過期的系統使用者字符自產生或重新整理之日起 60 天內有效。若要建立連續性，開發人員應在 60 天內重新整理存取字符。否則會導致存取字符被沒收，並且需要開發人員獲取新的存取字符才能重新獲取 API 存取權。請參閱[重新整理存取字符](https://developers.facebook.com/docs/marketing-api/system-users/install-apps-and-generate-tokens/)。 若要設定 Instagram Ads 連線： 1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線： 1. 選取**連線類型**時，請選取 Instagram Ads。 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. 提供使用者管理的用戶端應用程式用戶端 ID。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。選取的機密需要具有值為連線應用程式中用戶端機密的金鑰 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET`。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 # 從 Instagram Ads 實體中讀取 **必要條件** 您想要從中讀取的 Instagram Ads 物件。將需要物件名稱。下表顯示支援的實體。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 行銷活動 | 是 | 是 | 否 | 是 | 是 | | 廣告集 | 是 | 是 | 否 | 是 | 是 | | 廣告 | 是 | 是 | 否 | 是 | 是 | | 廣告創意 | 否 | 是 | 否 | 是 | 否 | | Insights - 帳戶 | 否 | 是 | 否 | 是 | 否 | | 廣告影像 | 是 | 是 | 否 | 是 | 否 | | Insights - 廣告 | 是 | 是 | 否 | 是 | 是 | | Insights - 廣告集 | 是 | 是 | 否 | 是 | 是 | | Insights - 行銷活動 | 是 | 是 | 否 | 是 | 是 | **範例**： ``` instagramAds_read = glueContext.create_dynamic_frame.from_options( connection_type="instagramads", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v20.0" } ``` ## Instagram Ads 實體和欄位詳細資訊 如需實體和欄位詳細資訊的更多資訊，請參閱： + [行銷活動](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group) + [廣告集](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign) + [廣告](https://developers.facebook.com/docs/marketing-api/reference/adgroup) + [廣告創意](https://developers.facebook.com/docs/marketing-api/reference/ad-creative) + [廣告帳戶深入分析](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights) + [廣告影像](https://developers.facebook.com/docs/marketing-api/reference/ad-image) + [廣告深入分析](https://developers.facebook.com/docs/marketing-api/reference/adgroup/insights/) + [廣告集深入分析](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/insights) + [行銷活動深入分析](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group/insights) 如需詳細資訊，請參閱[行銷 API](https://developers.facebook.com/docs/marketing-api/reference/v21.0)。 **注意** 在連接器的回應中，Struct 和 List 資料類型會轉換為 String 資料類型。 ## 分區查詢 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 DateTime 欄位，我們接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。 有效值範例： ``` "2022-01-01T00:00:00.000Z" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 有效值範例： ``` "2024-01-02T00:00:00.000Z" ``` + `NUM_PARTITIONS`：分區數目。 範例： ``` instagramADs_read = glueContext.create_dynamic_frame.from_options( connection_type="instagramads", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v20.0", "PARTITION_FIELD": "created_time" "LOWER_BOUND": "2022-01-01T00:00:00.000Z" "UPPER_BOUND": "2024-01-02T00:00:00.000Z" "NUM_PARTITIONS": "10" } ``` # Instagram Ads 連線選項 以下是 Instagram Ads 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Instagram Ads 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Instagram Ads Graph API 版本。例如：v21。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 + `PARTITION_FIELD`(String) - 用於讀取。用於分區查詢的欄位。 + `LOWER_BOUND`(String) - 用於讀取。所選分區欄位的包含下限值。 + `UPPER_BOUND`(String) - 用於讀取。所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。 # Instagram Ads 連接器的限制和備註 以下是 Instagram Ads 連接器的限制或備註： + 應用程式的呼叫計數是使用者在滾動一小時時段 200 期間可以進行的呼叫次數乘以使用者數目。如需速率限制詳細資訊，請參閱[速率限制](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/)與[商業使用案例速率限制](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#buc-rate-limits)。