# Connecting to Instagram Ads Connecting to Instagram Ads Instagram is a popular photo-sharing app that lets you connect with brands, celebrities, thought leaders, friends, family, and more. It is a photo-sharing and social networking service. Users can take photos or short videos and share them with their followers. Instagram ads are posts for which businesses can pay to serve to Instagram users. **Topics** + [ # AWS Glue support for Instagram Ads ](instagram-ads-support.md) + [ # Policies containing the API operations for creating and using connections ](instagram-ads-configuring-iam-permissions.md) + [ # Configuring Instagram Ads ](instagram-ads-configuring.md) + [ # Configuring Instagram Ads connections ](instagram-ads-configuring-connections.md) + [ # Reading from Instagram Ads entities ](instagram-ads-reading-from-entities.md) + [ # Instagram Ads connection options ](instagram-ads-connection-options.md) + [ # Limitations and notes for Instagram Ads connector ](instagram-ads-connector-limitations.md) # AWS Glue support for Instagram Ads AWS Glue supports Instagram Ads as follows: **Supported as a source?** Yes. You can use AWS Glue ETL jobs to query data from Instagram Ads. **Supported as a target?** No. **Supported Instagram Ads API versions** The following Instagram Ads API versions are supported: + v17.0 + v18.0 + v19.0 + v20.0 # Policies containing the API operations for creating and using connections IAM policies The following sample policy describes the required AWS IAM permissions for creating and using connections. If you are creating a new role, create a policy that contains the following: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:ListConnectionTypes", "glue:DescribeConnectionType", "glue:RefreshOAuth2Tokens", "glue:ListEntities", "glue:DescribeEntity" ], "Resource": "*" } ] } ``` ------ If you don't want to use the above method, alternatively use the following managed IAM policies: + [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – Grants access to resources that various AWS Glue processes require to run on your behalf. These resources include AWS Glue, Amazon S3, IAM, CloudWatch Logs, and Amazon EC2. If you follow the naming convention for resources specified in this policy, AWS Glue processes have the required permissions. This policy is typically attached to roles specified when defining crawlers, jobs, and development endpoints. + [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess) – Grants full access to AWS Glue resources when an identity that the policy is attached to uses the AWS Management Console. If you follow the naming convention for resources specified in this policy, users have full console capabilities. This policy is typically attached to users of the AWS Glue console. # Configuring Instagram Ads Before you can use AWS Glue to transfer data from Instagram Ads, you must meet these requirements: ## Minimum requirements The following are minimum requirements: + Instagram Standard accounts are accessed indirectly through Facebook. + User authentication is needed to generate the access token. + The Instagram Ads SDK connector will be implementing the *User Access Token OAuth* flow. + We are using OAuth2.0 to authenticate our API requests to Instagram Ads. This web-based authentication falls under the Multi-Factor Authentication (MFA) architecture, which is a superset of 2FA. + The user needs to grant permissions to access the end points. For accessing the user's data, endpoint authorization is handled through [permissions](https://developers.facebook.com/docs/permissions) and [features](https://developers.facebook.com/docs/features-reference). ## Getting OAuth 2.0 credentials To obtain API credentials so that you can make authenticated calls to your instance, see [Graph API](https://developers.facebook.com/docs/graph-api/). # Configuring Instagram Ads connections Instagram Ads supports the AUTHORIZATION\$1CODE grant type for OAuth2. + This grant type is considered three-legged OAuth as it relies on redirecting users to the third-party authorization server to authenticate the user. It is used when creating connections via the AWS Glue console. + Users may opt to create their own connected app in Instagram Ads and provide their own client ID and client secret when creating connections through the AWS Glue console. In this scenario, they will still be redirected to Instagram Ads to login and authorize AWS Glue to access their resources. + This grant type results in an access token. An expiring system user token is valid for 60 days from a generated or refreshed date. To create continuity, the developer should refresh the access token within 60 days. Failing to do so results in forfeiting the access token and requires the developer obtain a new one to regain API access. See [Refresh Access Token](https://developers.facebook.com/docs/marketing-api/system-users/install-apps-and-generate-tokens/). To configure a Instagram Ads connection: 1. In AWS Glue Glue Studio, create a connection under **Data Connections** by following the steps below: 1. When selecting a **Connection type**, select Instagram Ads. 1. Select the AWS IAM role which AWS Glue can assume and has permissions for the following actions: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. Provide the User Managed Client Application Client ID. 1. Select the `secretName` which you want to use for this connection in AWS Glue to put the tokens. The selected secret needs to have a key `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` with the value being the Client Secret from the connected app. 1. Select the network options if you want to use your network. 1. Grant the IAM role associated with your AWS Glue job permission to read `secretName`. # Reading from Instagram Ads entities **Prerequisite** A Instagram Ads object you would like to read from. You will need the object name. The following tables shows the supported entities. **Supported entities for source**: | Entity | Can be filtered | Supports limit | Supports Order by | Supports Select \$1 | Supports partitioning | | --- | --- | --- | --- | --- | --- | | Campaign | Yes | Yes | No | Yes | Yes | | Ad Set | Yes | Yes | No | Yes | Yes | | Ads | Yes | Yes | No | Yes | Yes | | Ad Creative | No | Yes | No | Yes | No | | Insights - Account | No | Yes | No | Yes | No | | Ad Image | Yes | Yes | No | Yes | No | | Insights - Ad | Yes | Yes | No | Yes | Yes | | Insights - AdSet | Yes | Yes | No | Yes | Yes | | Insights - Campaign | Yes | Yes | No | Yes | Yes | **Example**: ``` instagramAds_read = glueContext.create_dynamic_frame.from_options( connection_type="instagramads", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v20.0" } ``` ## Instagram Ads entity and field details For more information about the entities and field details see: + [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) + [Ad Account Insight](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights) + [Ad Image](https://developers.facebook.com/docs/marketing-api/reference/ad-image) + [Ad Insights](https://developers.facebook.com/docs/marketing-api/reference/adgroup/insights/) + [AdSets Insights](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/insights) + [Campaigns Insights](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group/insights) For more information, see [Marketing API](https://developers.facebook.com/docs/marketing-api/reference/v21.0). **Note** Struct and List data types are converted to String data type in the response of the connectors. ## Partitioning queries You can provide the additional Spark options `PARTITION_FIELD`, `LOWER_BOUND`, `UPPER_BOUND`, and `NUM_PARTITIONS` if you want to utilize concurrency in Spark. With these parameters, the original query would be split into `NUM_PARTITIONS` number of sub-queries that can be executed by Spark tasks concurrently. + `PARTITION_FIELD`: the name of the field to be used to partition the query. + `LOWER_BOUND`: an **inclusive** lower bound value of the chosen partition field. For the DateTime field, we accept the Spark timestamp format used in Spark SQL queries. Example of valid value: ``` "2022-01-01T00:00:00.000Z" ``` + `UPPER_BOUND`: an **exclusive** upper bound value of the chosen partition field. Example of valid value: ``` "2024-01-02T00:00:00.000Z" ``` + `NUM_PARTITIONS`: the number of partitions. Example: ``` 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 connection options The following are connection options for Instagram Ads: + `ENTITY_NAME`(String) - (Required) Used for read. The name of your object in Instagram Ads. + `API_VERSION`(String) - (Required) Used for read. Instagram Ads Graph API version you want to use. For example: v21. + `SELECTED_FIELDS`(List) - Default: empty(SELECT \$1). Used for read. Columns you want to select for the object. + `FILTER_PREDICATE`(String) - Default: empty. Used for read. It should be in the Spark SQL format. + `QUERY`(String) - Default: empty. Used for read. Full Spark SQL query. + `PARTITION_FIELD`(String) - Used for read. Field to be used to partition query. + `LOWER_BOUND`(String)- Used for read. An inclusive lower bound value of the chosen partition field. + `UPPER_BOUND`(String) - Used for read. An exclusive upper bound value of the chosen partition field. + `NUM_PARTITIONS`(Integer) - Default: 1. Used for read. Number of partitions for read. # Limitations and notes for Instagram Ads connector The following are limitations or notes for the Instagram Ads connector: + An app's call count is the number of calls a user can make during a rolling one-hour window 200 multiplied by the number of users. For rate limit details, see [Rate Limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/), and [Business Use Case Rate Limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#buc-rate-limits).