meltano-tap-facebook


Namemeltano-tap-facebook JSON
Version 0.6.1 PyPI version JSON
download
home_pageNone
Summary`tap-facebook` is a Singer tap for facebook, built with the Meltano SDK for Singer Taps.
upload_time2024-12-10 23:34:10
maintainerNone
docs_urlNone
authorMeltano
requires_python>=3.9
licenseElastic-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": null,
    "name": "meltano-tap-facebook",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "ELT, facebook",
    "author": "Meltano",
    "author_email": "hello@meltano.com",
    "download_url": "https://files.pythonhosted.org/packages/77/02/d502d77ce95f2a4a54862784e7a62b807886d637183a54e5ed52e6b76ebe/meltano_tap_facebook-0.6.1.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.6.1",
    "project_urls": null,
    "split_keywords": [
        "elt",
        " facebook"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "b7307588d9b124d1a82c79f9ea9da3591ce6b63ff77b1ef5a6074bb4dca9706c",
                "md5": "a47b461ff07c4ac149f1a37d377ad581",
                "sha256": "ece09a5f22968a40f34b5a0a8d42a3d1114f762b4b71b92d3a85b87e19962474"
            },
            "downloads": -1,
            "filename": "meltano_tap_facebook-0.6.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "a47b461ff07c4ac149f1a37d377ad581",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 27192,
            "upload_time": "2024-12-10T23:34:09",
            "upload_time_iso_8601": "2024-12-10T23:34:09.150510Z",
            "url": "https://files.pythonhosted.org/packages/b7/30/7588d9b124d1a82c79f9ea9da3591ce6b63ff77b1ef5a6074bb4dca9706c/meltano_tap_facebook-0.6.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "7702d502d77ce95f2a4a54862784e7a62b807886d637183a54e5ed52e6b76ebe",
                "md5": "392e63f3162e0967a1bd42ac9232c230",
                "sha256": "14350c7b5c5223a43a572ed5ffdd531ff6f868abaafe1578978df07ac4c0845e"
            },
            "downloads": -1,
            "filename": "meltano_tap_facebook-0.6.1.tar.gz",
            "has_sig": false,
            "md5_digest": "392e63f3162e0967a1bd42ac9232c230",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 20515,
            "upload_time": "2024-12-10T23:34:10",
            "upload_time_iso_8601": "2024-12-10T23:34:10.690862Z",
            "url": "https://files.pythonhosted.org/packages/77/02/d502d77ce95f2a4a54862784e7a62b807886d637183a54e5ed52e6b76ebe/meltano_tap_facebook-0.6.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-12-10 23:34:10",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "meltano-tap-facebook"
}
        
Elapsed time: 0.51861s