| Name | meltano-tap-facebook JSON |
| Version |
0.3.4
JSON |
| download |
| home_page | |
| Summary | `tap-facebook` is a Singer tap for facebook, built with the Meltano SDK for Singer Taps. |
| upload_time | 2024-03-12 15:53:51 |
| maintainer | |
| docs_url | None |
| author | Meltano |
| requires_python | >=3.8 |
| license | Elastic-2.0 |
| keywords |
elt
facebook
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# `tap-facebook`
Singer tap for extracting data from the Facebook Marketing API.
Built with the [Meltano Singer SDK](https://sdk.meltano.com).
## Capabilities
* `catalog`
* `state`
* `discover`
* `about`
* `stream-maps`
* `schema-flattening`
## Settings
| Setting | Required | Default | Description |
|:--------------------|:--------:|:-------:|:------------|
| access_token | True | None | The token to authenticate against the API service |
| api_version | False | v16.0 | The API version to request data from. |
| account_id | True | None | Your Facebook Account ID. |
| start_date | False | None | The earliest record date to sync |
| end_date | False | None | The latest record date to sync |
| stream_maps | False | None | Config object for stream maps capability. For more information check out [Stream Maps](https://sdk.meltano.com/en/latest/stream_maps.html). |
| stream_map_config | False | None | User-defined config values to be used within map expressions. |
| flattening_enabled | False | None | 'True' to enable schema flattening and automatically expand nested properties. |
| flattening_max_depth| False | None | The max depth to flatten schemas. |
A full list of supported settings and capabilities is available by running: `tap-facebook --about`
## Installation
```bash
pipx install git+https://github.com/MeltanoLabs/tap-facebook.git
```
## Configuration
### Meltano Variables
The following config values need to be set in order to use with Meltano. These can be set in `meltano.yml`, via
```meltano config tap-facebook set --interactive```, or via the env var mappings shown above.
- `access_token:` access token from TAP_FACEBOOK_ACCESS_TOKEN variable
- `start_date:` start date
- `end_date:` end_date
- `account_id:` account ID from TAP_FACEBOOK_ACCOUNT_ID variable
- `api_version:` api version
```bash
tap-facebook --about
```
### Elastic License 2.0
The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software.
### Attribution Window
Attribution Window is time period during which conversions might be credited to ads, we can have this time period between 1 day to 7 days for clicks and views
- `action_attribution_windows:` We can add these variable to params, it will have a list type value which takes in 1d-7d clicks and 1d-7d views values. We have added
this variable in get_url_params function of ads insights stream
### Authentication
A Facebook access token is required to make API requests. (See [Facebook API](https://developers.facebook.com/docs/facebook-login/guides/access-tokens/) docs for more info)
## Usage
### API Limitation - Rate Limits
Hitting the rate limit for the Facebook API while making requests will return the following error:
```
400 Client Error: b'{"error":{"message":"(#80004) There have been too many calls to this ad-account. Wait a bit and try again
```
This error is handled using the [Backoff Library](https://github.com/litl/backoff), and the program will cease for a random amount of time before
attempting to call the API again
### Executing the Tap Directly
```bash
tap-facebook --version
tap-facebook --help
tap-facebook --config CONFIG --discover > ./catalog.json
```
## Contributing
This project uses parent-child streams. Learn more about them [here](https://gitlab.com/meltano/sdk/-/blob/main/docs/parent_streams.md).
### Initialize your Development Environment
```bash
pipx install poetry
poetry install
```
### Create and Run Tests
Create tests within the `tap_facebook/tests` subfolder and
then run:
```bash
poetry run pytest
```
You can also test the `tap-facebook` CLI interface directly using `poetry run`:
```bash
poetry run tap-facebook --help
```
### Testing with [Meltano](https://www.meltano.com)
_**Note:** This tap will work in any Singer environment and does not require Meltano.
Examples here are for convenience and to streamline end-to-end orchestration scenarios._
Your project comes with a custom `meltano.yml` project file already created. Open the `meltano.yml` and follow any _"TODO"_ items listed in
the file.
Next, install Meltano (if you haven't already) and any needed plugins:
```bash
# Install meltano
pipx install meltano
# Initialize meltano within this directory
cd tap-facebook
meltano install
```
Now you can test and orchestrate using Meltano:
```bash
# Test invocation:
meltano invoke tap-facebook --version
# OR run a test `elt` pipeline:
meltano elt tap-facebook target-jsonl
```
### SDK Dev Guide
See the [dev guide](https://sdk.meltano.com/en/latest/dev_guide.html) for more instructions on how to use the SDK to
develop your own taps and targets.
Raw data
{
"_id": null,
"home_page": "",
"name": "meltano-tap-facebook",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "ELT,facebook",
"author": "Meltano",
"author_email": "hello@meltano.com",
"download_url": "https://files.pythonhosted.org/packages/28/38/2ed0e950933268d6905df8ecaf8e2b43461b45d31aeb099f58072fd8c760/meltano_tap_facebook-0.3.4.tar.gz",
"platform": null,
"description": "# `tap-facebook`\n\nSinger tap for extracting data from the Facebook Marketing API.\n\nBuilt with the [Meltano Singer SDK](https://sdk.meltano.com).\n\n## Capabilities\n\n* `catalog`\n* `state`\n* `discover`\n* `about`\n* `stream-maps`\n* `schema-flattening`\n\n## Settings\n\n| Setting | Required | Default | Description |\n|:--------------------|:--------:|:-------:|:------------|\n| access_token | True | None | The token to authenticate against the API service |\n| api_version | False | v16.0 | The API version to request data from. |\n| account_id | True | None | Your Facebook Account ID. |\n| start_date | False | None | The earliest record date to sync |\n| end_date | False | None | The latest record date to sync |\n| stream_maps | False | None | Config object for stream maps capability. For more information check out [Stream Maps](https://sdk.meltano.com/en/latest/stream_maps.html). |\n| stream_map_config | False | None | User-defined config values to be used within map expressions. |\n| flattening_enabled | False | None | 'True' to enable schema flattening and automatically expand nested properties. |\n| flattening_max_depth| False | None | The max depth to flatten schemas. |\n\nA full list of supported settings and capabilities is available by running: `tap-facebook --about`\n\n\n## Installation\n\n```bash\npipx install git+https://github.com/MeltanoLabs/tap-facebook.git\n```\n\n## Configuration\n\n### Meltano Variables\n\nThe following config values need to be set in order to use with Meltano. These can be set in `meltano.yml`, via\n```meltano config tap-facebook set --interactive```, or via the env var mappings shown above.\n\n- `access_token:` access token from TAP_FACEBOOK_ACCESS_TOKEN variable\n- `start_date:` start date\n- `end_date:` end_date\n- `account_id:` account ID from TAP_FACEBOOK_ACCOUNT_ID variable\n- `api_version:` api version\n\n```bash\ntap-facebook --about\n```\n\n### Elastic License 2.0\n\nThe licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software.\n\n### Attribution Window\n\nAttribution Window is time period during which conversions might be credited to ads, we can have this time period between 1 day to 7 days for clicks and views\n\n- `action_attribution_windows:` We can add these variable to params, it will have a list type value which takes in 1d-7d clicks and 1d-7d views values. We have added\nthis variable in get_url_params function of ads insights stream\n\n\n### Authentication\n\nA Facebook access token is required to make API requests. (See [Facebook API](https://developers.facebook.com/docs/facebook-login/guides/access-tokens/) docs for more info)\n\n\n## Usage\n\n### API Limitation - Rate Limits\n\nHitting the rate limit for the Facebook API while making requests will return the following error:\n\n```\n400 Client Error: b'{\"error\":{\"message\":\"(#80004) There have been too many calls to this ad-account. Wait a bit and try again\n```\n\nThis error is handled using the [Backoff Library](https://github.com/litl/backoff), and the program will cease for a random amount of time before\nattempting to call the API again\n\n### Executing the Tap Directly\n\n```bash\ntap-facebook --version\ntap-facebook --help\ntap-facebook --config CONFIG --discover > ./catalog.json\n```\n\n## Contributing\n\nThis project uses parent-child streams. Learn more about them [here](https://gitlab.com/meltano/sdk/-/blob/main/docs/parent_streams.md).\n\n### Initialize your Development Environment\n\n```bash\npipx install poetry\npoetry install\n```\n\n### Create and Run Tests\n\nCreate tests within the `tap_facebook/tests` subfolder and\n then run:\n\n```bash\npoetry run pytest\n```\n\nYou can also test the `tap-facebook` CLI interface directly using `poetry run`:\n\n```bash\npoetry run tap-facebook --help\n```\n\n### Testing with [Meltano](https://www.meltano.com)\n\n_**Note:** This tap will work in any Singer environment and does not require Meltano.\nExamples here are for convenience and to streamline end-to-end orchestration scenarios._\n\nYour project comes with a custom `meltano.yml` project file already created. Open the `meltano.yml` and follow any _\"TODO\"_ items listed in\nthe file.\n\nNext, install Meltano (if you haven't already) and any needed plugins:\n\n```bash\n# Install meltano\npipx install meltano\n# Initialize meltano within this directory\ncd tap-facebook\nmeltano install\n```\n\nNow you can test and orchestrate using Meltano:\n\n```bash\n# Test invocation:\nmeltano invoke tap-facebook --version\n# OR run a test `elt` pipeline:\nmeltano elt tap-facebook target-jsonl\n```\n\n### SDK Dev Guide\n\nSee the [dev guide](https://sdk.meltano.com/en/latest/dev_guide.html) for more instructions on how to use the SDK to\ndevelop your own taps and targets.\n\n",
"bugtrack_url": null,
"license": "Elastic-2.0",
"summary": "`tap-facebook` is a Singer tap for facebook, built with the Meltano SDK for Singer Taps.",
"version": "0.3.4",
"project_urls": null,
"split_keywords": [
"elt",
"facebook"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6ebf8d13671402fcd643f1c2efb84be9775e8435e71b9613aadb42ac9f3ed148",
"md5": "7d77a6e5575bcfb15534ff2169a0a52b",
"sha256": "3a39cf2e8965ce055196b5e9d9d5cd5577babcd3537851ec003bb34efba89e06"
},
"downloads": -1,
"filename": "meltano_tap_facebook-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d77a6e5575bcfb15534ff2169a0a52b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26632,
"upload_time": "2024-03-12T15:53:50",
"upload_time_iso_8601": "2024-03-12T15:53:50.108516Z",
"url": "https://files.pythonhosted.org/packages/6e/bf/8d13671402fcd643f1c2efb84be9775e8435e71b9613aadb42ac9f3ed148/meltano_tap_facebook-0.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "28382ed0e950933268d6905df8ecaf8e2b43461b45d31aeb099f58072fd8c760",
"md5": "c79ce0e26c7c45653eb9800e6d01e913",
"sha256": "27af32eeaf8df335e51d215076c59b60cd44b2a5b3d03495716ead20f5534d8c"
},
"downloads": -1,
"filename": "meltano_tap_facebook-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "c79ce0e26c7c45653eb9800e6d01e913",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19996,
"upload_time": "2024-03-12T15:53:51",
"upload_time_iso_8601": "2024-03-12T15:53:51.899545Z",
"url": "https://files.pythonhosted.org/packages/28/38/2ed0e950933268d6905df8ecaf8e2b43461b45d31aeb099f58072fd8c760/meltano_tap_facebook-0.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-12 15:53:51",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "meltano-tap-facebook"
}
