0
# Apache Airflow Providers Facebook
1

2
A provider package that enables Apache Airflow to integrate with Facebook Ads API for advertising data collection and reporting. The package provides a FacebookAdsReportingHook that wraps the Facebook Business SDK to authenticate with Facebook Ads API, execute asynchronous report generation jobs, and retrieve advertising insights and metrics.
3

4
## Package Information
5

6
- **Package Name**: apache-airflow-providers-facebook
7
- **Package Type**: pypi  
8
- **Language**: Python
9
- **Installation**: `pip install apache-airflow-providers-facebook`
10
- **Dependencies**: `facebook-business>=6.0.2`
11

12
## Core Imports
13

14
```python
15
from airflow.providers.facebook.ads.hooks.ads import FacebookAdsReportingHook, JobStatus
16
```
17

18
Additional imports for type annotations:
19

20
```python
21
from facebook_business.adobjects.adsinsights import AdsInsights
22
from facebook_business.api import FacebookAdsApi
23
from typing import Any, Dict, List
24
```
25

26
## Basic Usage
27

28
```python
29
from airflow.providers.facebook.ads.hooks.ads import FacebookAdsReportingHook
30

31
# Initialize the hook with connection details
32
hook = FacebookAdsReportingHook(
33
    facebook_conn_id='facebook_default',
34
    api_version='v6.0'
35
)
36

37
# Define report parameters
38
params = {
39
    'level': 'ad',
40
    'date_preset': 'yesterday',
41
    'time_range': {
42
        'since': '2021-01-01',
43
        'until': '2021-01-31'
44
    }
45
}
46

47
# Define fields to retrieve
48
fields = [
49
    'campaign_name',
50
    'campaign_id', 
51
    'ad_id',
52
    'clicks',
53
    'impressions',
54
    'spend'
55
]
56

57
# Execute bulk Facebook report
58
insights = hook.bulk_facebook_report(
59
    params=params,
60
    fields=fields,
61
    sleep_time=5
62
)
63

64
# Process the results
65
for insight in insights:
66
    print(f"Campaign: {insight['campaign_name']}, Clicks: {insight['clicks']}")
67
```
68

69
## Architecture
70

71
The Facebook Ads provider is built around the FacebookAdsReportingHook which integrates with the Facebook Business SDK:
72

73
- **Hook Integration**: Extends Airflow's BaseHook to provide Facebook Ads API connectivity
74
- **Async Reporting**: Uses Facebook's asynchronous reporting API for handling large data requests
75
- **Connection Management**: Leverages Airflow's connection system for secure credential storage
76
- **Error Handling**: Provides comprehensive error handling for API failures and job status monitoring
77
- **SDK Wrapper**: Acts as a bridge between Airflow and the facebook-business Python SDK
78

79
## Capabilities
80

81
### Facebook Ads Reporting Hook
82

83
Main hook class for integrating with Facebook Ads API, providing authentication and asynchronous report generation capabilities.
84

85
```python { .api }
86
class FacebookAdsReportingHook(BaseHook):
87
    """
88
    Hook for the Facebook Ads API
89
    """
90
    
91
    conn_name_attr = 'facebook_conn_id'
92
    default_conn_name = 'facebook_default' 
93
    conn_type = 'facebook_social'
94
    hook_name = 'Facebook Ads'
95
    
96
    def __init__(
97
        self,
98
        facebook_conn_id: str = 'facebook_default',
99
        api_version: str = "v6.0"
100
    ) -> None:
101
        """
102
        Initialize the Facebook Ads Reporting Hook.
103
        
104
        Args:
105
            facebook_conn_id (str): Airflow Facebook Ads connection ID (default: 'facebook_default')
106
            api_version (str): The version of Facebook API (default: 'v6.0')
107
        """
108
    
109
    client_required_fields = ["app_id", "app_secret", "access_token", "account_id"]
110
```
111

112
### Facebook Ads API Service
113

114
Returns Facebook Ads Client using a service account with authenticated configuration.
115

116
```python { .api }
117
def _get_service(self) -> FacebookAdsApi:
118
    """
119
    Returns Facebook Ads Client using a service account.
120
    
121
    Returns:
122
        FacebookAdsApi: Initialized Facebook Ads API client
123
    """
124
```
125

126
### Bulk Report Generation
127

128
Executes asynchronous Facebook Ads reporting queries and returns insights data.
129

130
```python { .api }
131
def bulk_facebook_report(
132
    self,
133
    params: Dict[str, Any],
134
    fields: List[str], 
135
    sleep_time: int = 5
136
) -> List[AdsInsights]:
137
    """
138
    Pulls data from the Facebook Ads API using asynchronous reporting.
139
    
140
    Args:
141
        params (Dict[str, Any]): Parameters that determine the query for Facebook.
142
                                 See https://developers.facebook.com/docs/marketing-api/insights/parameters/v6.0
143
        fields (List[str]): List of fields obtained from Facebook AdsInsights.Field class.
144
                           See https://developers.facebook.com/docs/marketing-api/insights/parameters/v6.0  
145
        sleep_time (int): Time to sleep when async call is happening (default: 5)
146
    
147
    Returns:
148
        List[AdsInsights]: Facebook Ads API response converted to Facebook Ads Row objects
149
        
150
    Raises:
151
        AirflowException: If async job fails, is skipped, or API communication errors occur
152
    """
153
```
154

155
### Connection Configuration
156

157
Retrieves and validates Facebook Ads connection configuration from Airflow metadata database.
158

159
```python { .api }
160
@cached_property
161
def facebook_ads_config(self) -> Dict:
162
    """
163
    Gets Facebook ads connection from meta db and sets facebook_ads_config attribute with returned config file.
164
    
165
    Returns:
166
        Dict: Facebook Ads configuration containing required fields (app_id, app_secret, access_token, account_id)
167
        
168
    Raises:
169
        AirflowException: If required fields are missing from connection configuration
170
    """
171
```
172

173

174
### Job Status Enumeration
175

176
Status values for Facebook asynchronous reporting tasks.
177

178
```python { .api }
179
class JobStatus(Enum):
180
    """Available options for facebook async task status"""
181
    
182
    COMPLETED = 'Job Completed'
183
    STARTED = 'Job Started' 
184
    RUNNING = 'Job Running'
185
    FAILED = 'Job Failed'
186
    SKIPPED = 'Job Skipped'
187
```
188

189
## Types
190

191
### Connection Configuration
192

193
The Facebook Ads connection must include the following fields in the `extra` configuration:
194

195
```python { .api }
196
FacebookAdsConfig = Dict[str, str]
197
# Required fields:
198
# - app_id: Facebook App ID
199
# - app_secret: Facebook App Secret  
200
# - access_token: Facebook Access Token
201
# - account_id: Facebook Ad Account ID
202
```
203

204
### Report Parameters
205

206
Configuration for Facebook Ads reporting queries:
207

208
```python { .api }
209
ReportParams = Dict[str, Any]
210
# Common parameters:
211
# - level: str - Reporting level ('account', 'campaign', 'adset', 'ad')
212
# - date_preset: str - Predefined date range ('today', 'yesterday', 'last_7_days', etc.)
213
# - time_range: Dict[str, str] - Custom date range with 'since' and 'until' keys
214
# - filtering: List[Dict] - Filters to apply to the data
215
# - breakdowns: List[str] - Dimensions to break down the data by
216
```
217

218
### Report Fields
219

220
Available fields for Facebook Ads insights reporting:
221

222
```python { .api }
223
ReportFields = List[str]
224
# Common fields include:
225
# - 'campaign_name', 'campaign_id'
226
# - 'adset_name', 'adset_id'  
227
# - 'ad_name', 'ad_id'
228
# - 'clicks', 'impressions', 'spend'
229
# - 'ctr', 'cpm', 'cpp'
230
# - 'reach', 'frequency'
231
# See Facebook Marketing API documentation for complete field list
232
```
233

234
## Error Handling
235

236
The hook raises `AirflowException` in the following scenarios:
237

238
- **Missing Connection Fields**: When required fields (`app_id`, `app_secret`, `access_token`, `account_id`) are missing from the connection configuration
239
- **Async Job Failure**: When the Facebook Ads async reporting job fails or is skipped
240
- **API Communication Errors**: When there are issues communicating with the Facebook Ads API
241

242
## Connection Setup
243

244
To use this provider, configure an Airflow connection with:
245

246
- **Connection Type**: `facebook_social`
247
- **Connection ID**: `facebook_default` (or custom)
248
- **Extra**: JSON object containing:
249
  ```json
250
  {
251
    "app_id": "your_facebook_app_id",
252
    "app_secret": "your_facebook_app_secret", 
253
    "access_token": "your_facebook_access_token",
254
    "account_id": "your_facebook_account_id"
255
  }
256
  ```
257

258
## API Version Support
259

260
The hook supports Facebook Marketing API versions, with v6.0 as the default. You can specify a different version during initialization:
261

262
```python
263
hook = FacebookAdsReportingHook(api_version='v12.0')
264
```