Apache Airflow Facebook Provider

3.9.4 · active · verified Fri Apr 17

This provider package integrates Apache Airflow with Facebook APIs, offering operators and hooks to interact with various Facebook services like Marketing and Prophet. It allows data engineers to programmatically manage and automate data workflows involving Facebook platforms. Current version is 3.9.4, with releases tied to the Apache Airflow release cycle.

Common errors

```
ModuleNotFoundError: No module named 'airflow.providers.facebook'
```
cause The `apache-airflow-providers-facebook` package has not been installed in your Airflow environment.

fix Install the provider using pip: `pip install apache-airflow-providers-facebook`
```
airflow.exceptions.AirflowException: Facebook Marketing API Error #100 Invalid parameter: message
```
cause One or more parameters passed to the operator are incorrect, malformed, or missing required values according to the Facebook API specification for the chosen method and path. This can also indicate insufficient permissions for the connected user/app.

fix Carefully review the operator's parameters against the official Facebook Marketing API documentation for the specific endpoint and API version you are targeting. Also, verify that the Facebook user/app associated with your access token has the necessary permissions.
```
airflow.exceptions.AirflowException: Facebook Marketing API Error #190 Error validating access token: Session has expired or is not valid for this access token.
```
cause The access token provided in the Airflow connection (`facebook_conn_id`) has expired, been revoked, or is otherwise invalid.

fix Generate a new long-lived access token from your Facebook Developer App and update the `facebook_marketing_default` (or your chosen) Airflow connection with the new token. Ensure the token has the required permissions.

Warnings

breaking Facebook API versions frequently introduce breaking changes or deprecate endpoints. The provider's functionality is tightly coupled to the underlying Facebook Marketing API version. Ensure your `api_version` in the Airflow connection or operator parameters matches a supported and active Facebook API version to avoid unexpected errors.
Fix: Regularly check Facebook Marketing API documentation for updates. Update `api_version` in your Airflow connection's 'Extra' field (e.g., `{"api_version": "v19.0"}`) or directly in the operator parameters if issues arise after Facebook API updates.
gotcha The provider relies on the `facebook-business` Python SDK. Incompatibilities can arise if your `facebook-business` package version is not aligned with the provider's expectations or if there are conflicts with other libraries. This can lead to unexpected runtime errors.
Fix: Refer to the `apache-airflow-providers-facebook` PyPI page or GitHub for specific `facebook-business` dependency ranges. Consider using a virtual environment and pinning dependency versions to ensure stability.
gotcha Authentication failures are common due to expired or invalid Facebook Access Tokens. Airflow connections for Facebook Marketing typically require a long-lived access token, which can still expire or be invalidated by Facebook security policies.
Fix: Ensure your Airflow connection (`facebook_conn_id`) uses a current and valid Facebook Access Token. Regularly check the token's validity in Facebook's developer tools and refresh if necessary. Consider using environment variables or a secrets backend for sensitive tokens instead of directly in the connection UI.
gotcha Facebook APIs have strict rate limits. Making too many requests in a short period can lead to throttling errors (e.g., HTTP 429). The provider itself does not inherently handle complex rate-limit backoff strategies for user-defined tasks.
Fix: Implement retry mechanisms with exponential backoff in your DAGs for tasks interacting with Facebook APIs. Design your DAGs to minimize concurrent requests and distribute load. Refer to Facebook's API rate limiting documentation.

Install

pip install apache-airflow-providers-facebook Install latest version

Imports

FacebookMarketingOperator

from airflow.providers.facebook.marketing.operators.marketing import FacebookMarketingOperator

FacebookMarketingHook

from airflow.providers.facebook.marketing.hooks.marketing import FacebookMarketingHook

FacebookProphetOperator

from airflow.providers.facebook.prophet.operators.prophet import ProphetOperator

Quickstart

This example DAG uses the `FacebookMarketingOperator` to fetch a list of ad accounts associated with the configured Facebook connection. It requires an Airflow connection named `facebook_marketing_default` with a valid Facebook Access Token. The access token can be stored in the 'Password' field or as part of the 'Extra' JSON for the connection.

from __future__ import annotations

import pendulum
import os

from airflow.models.dag import DAG
from airflow.providers.facebook.marketing.operators.marketing import FacebookMarketingOperator

# NOTE: Ensure you have an Airflow Connection named 'facebook_marketing_default'
# with your Facebook Access Token (e.g., in the 'Password' field or 'Extra' JSON).
# Example Extra: {"access_token": "YOUR_ACCESS_TOKEN", "api_version": "v19.0"}

with DAG(
    dag_id="facebook_marketing_example",
    start_date=pendulum.datetime(2023, 1, 1, tz="UTC"),
    schedule=None,
    catchup=False,
    tags=["facebook", "marketing", "example"],
    doc_md="""
    ### Facebook Marketing Example DAG
    A simple DAG demonstrating how to use the FacebookMarketingOperator to fetch ad accounts.
    Requires a 'facebook_marketing_default' Airflow connection with an access token.
    """
) as dag:
    get_ad_accounts = FacebookMarketingOperator(
        task_id="get_ad_accounts",
        facebook_conn_id="facebook_marketing_default",
        api_method="GET",
        api_path="/me/adaccounts",
        fields=["id", "name", "account_status"],
        result_processor=lambda result: print(f"Fetched Ad Accounts: {result}")
    )

view raw JSON →