Create additional setup guides for top API sources #27101
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| ## Prerequisites | ||
|
|
||
| - API Access Key | ||
|
|
||
| In order to get a free `API Access Key` please go to [this](https://manage.exchangeratesapi.io/signup/free) page and enter the required information. After registration and login, you will see your `API Access Key`. You can also locate it [here](https://manage.exchangeratesapi.io/dashboard). | ||
|
|
||
| If you have a `free` subscription plan, you will have two limitations to the plan: | ||
|
|
||
| 1. Limit of 1,000 API calls per month | ||
| 2. You won't be able to specify the `base` parameter, meaning that you will be only be allowed to use the default base value which is EUR. | ||
|
|
||
| ## Setup guide | ||
| 1. Enter a **Name** for your source. | ||
| 2. Enter your **API key** as the `access_key` from the prerequisites. | ||
| 3. Enter the **Start Date** in YYYY-MM-DD format. The data added on and after this date will be replicated. | ||
| 4. (Optional) Enter a **base** currency. For those on the free plan, `EUR` is the only option available. If none are specified, `EUR` will be used. | ||
| 5. Click **Set up source**. | ||
|
|
||
| ### Exchange Rates data output | ||
| - The sync will include one stream: `exchange_rates` | ||
| - Each record in the stream contains many fields: | ||
| - The date of the record | ||
| - One field for every supported [currency](https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html) which contain the value of that currency on that date. | ||
|
|
||
| For detailed information on supported sync modes, supported streams, performance considerations, refer to the full documentation for [Exchange Rates](https://docs.airbyte.com/integrations/sources/exchange-rates/). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| ## Prerequisites | ||
|
|
||
| - A [Google Ads Account](https://support.google.com/google-ads/answer/6366720) [linked](https://support.google.com/google-ads/answer/7459601) to a [Google Ads Manager account](https://ads.google.com/home/tools/manager-accounts/) | ||
|
|
||
| ## Setup guide | ||
| 1. Enter a **Name** for your source. | ||
| 2. Click **Sign in with Google** to authenticate your Google Ads account. | ||
| 3. Enter a comma-separated list of the [Customer ID(s)](https://support.google.com/google-ads/answer/1704344) for your account. | ||
| 4. Enter the **Start Date** in YYYY-MM-DD format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data. | ||
| 5. (Optional) Enter a custom [GAQL](#custom-query-understanding-google-ads-query-language) query. | ||
| 6. (Optional) If the access to your account is through a [Google Ads Manager account](https://ads.google.com/home/tools/manager-accounts/), enter the [**Login Customer ID for Managed Accounts**](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid) of the Google Ads Manager account. | ||
| 7. (Optional) Enter a [**Conversion Window**](https://support.google.com/google-ads/answer/3123169?hl=en). | ||
| 8. (Optional) Enter the **End Date** in YYYY-MM-DD format. The data added after this date will not be replicated. | ||
| 9. Click **Set up source**. | ||
|
|
||
| ## Custom Query: Understanding Google Ads Query Language | ||
| Additional streams for Google Ads can be dynamically created using custom queries. | ||
|
|
||
| The Google Ads Query Language queries the Google Ads API. Review the [Google Ads Query Language](https://developers.google.com/google-ads/api/docs/query/overview) and the [query builder](https://developers.google.com/google-ads/api/fields/v13/query_validator) to validate your query. You can then add these as custom queries when configuring the Google Ads source. | ||
|
|
||
| Example GAQL Custom Query: | ||
| ``` | ||
| SELECT | ||
| campaign.name, | ||
| metrics.conversions, | ||
| metrics.conversions_by_conversion_date | ||
| FROM ad_group | ||
| ``` | ||
| Note the segments.date is automatically added to the output, and does not need to be specified in the custom query. All custom reports will by synced by day. | ||
|
|
||
| Each custom query in the input configuration must work for all the customer account IDs. Otherwise, the customer ID will be skipped for every query that fails the validation test. For example, if your query contains metrics fields in the select clause, it will not be executed against manager accounts. | ||
|
|
||
| Follow Google's guidance on [Selectability between segments and metrics](https://developers.google.com/google-ads/api/docs/reporting/segmentation#selectability_between_segments_and_metrics) when editing custom queries or default stream schemas (which will also be turned into GAQL queries by the connector). Fields like `segments.keyword.info.text`, `segments.keyword.info.match_type`, `segments.keyword.ad_group_criterion` in the `SELECT` clause tell the query to only get the rows of data that have keywords and remove any row that is not associated with a keyword. This is often unobvious and undesired behavior and can lead to missing data records. If you need this field in the stream, add a new stream instead of editing the existing ones. | ||
|
|
||
| :::info | ||
| For an existing Google Ads source, when you are updating or removing Custom GAQL Queries, you should also subsequently refresh your source schema to pull in any changes. | ||
| ::: | ||
|
|
||
| For detailed information on supported sync modes, supported streams, performance considerations, refer to the full documentation for [Google Ads](https://docs.airbyte.com/integrations/sources/google-ads/). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| ## Prerequisites | ||
|
|
||
| - Access to a Google Sheet | ||
|
|
||
| :::info | ||
| The Google Sheets source connector pulls data from a single Google Sheets spreadsheet. To replicate multiple spreadsheets, set up multiple Google Sheets source connectors in your Airbyte instance. | ||
| ::: | ||
|
|
||
| ## Setup guide | ||
|
|
||
| 1. Enter a name for the Google Sheets connector. | ||
| 2. Authenticate your Google account via OAuth or Service Account Key Authentication. | ||
| - **(Recommended)** To authenticate your Google account via OAuth, click **Sign in with Google** and complete the authentication workflow. | ||
| - To authenticate your Google account via Service Account Key Authentication, enter your [Google Cloud service account key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating_service_account_keys) in JSON format. Make sure the Service Account has the Project Viewer permission. If your spreadsheet is viewable by anyone with its link, no further action is needed. If not, [give your Service account access to your spreadsheet](https://youtu.be/GyomEw5a2NQ%22). | ||
| 3. For **Spreadsheet Link**, enter the link to the Google spreadsheet. To get the link, go to the Google spreadsheet you want to sync, click **Share** in the top right corner, and click **Copy Link**. | ||
| 4. For **Row Batch Size**, define the number of records you want the Google API to fetch at a time. The default value is 200. | ||
|
|
||
| ### Google Sheets format requirements | ||
| - Sheet names and column headers must only contain alphanumeric characters or `_`, as specified in the [**Airbyte Protocol**](../../understanding-airbyte/airbyte-protocol.md). For example, if your sheet or column header is named `the data`, rename it to `the_data`. This restriction does not apply to non-header cell values. | ||
| - Airbyte only supports replicating [Grid](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/sheets#SheetType) sheets. | ||
|
|
||
| For detailed information on supported sync modes, supported streams, performance considerations, refer to the full documentation for [Google Sheets](https://docs.airbyte.com/integrations/sources/google-sheets/). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| ## Prerequisites | ||
|
|
||
| - Access to a JIRA account | ||
| - [JIRA API Token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) | ||
| - JIRA Account Domain | ||
|
|
||
| ## Setup guide | ||
|
|
||
| 1. Enter a name for the connector. | ||
| 2. Enter the **API Token** that you have created. The **API Token** is used for Authorization to your account. | ||
| 2. Enter the **Domain** for your Jira account, e.g. `airbyte.atlassian.net`. | ||
| 3. Enter the **Email** for your Jira account which you used to generate the API token. This field is used for Authorization to your account. | ||
| 4. (Optional) Enter the list of **Projects** for which you need to replicate data. If empty, data from all projects will be replicated. | ||
| 5. (Optional) Enter the **Start Date** from which you'd like to replicate data for Jira in the format YYYY-MM-DDTHH:MM:SSZ. All data generated after this date will be replicated. If empty, all data will be replicated. Note that it will be used only in the following streams: `BoardIssues`, `IssueComments`, `IssueProperties`, `IssueRemoteLinks`, `IssueVotes`, `IssueWatchers`, `IssueWorklogs`, `Issues`, `PullRequests`, `SprintIssues`. For other streams, it will replicate all data. | ||
| 9. Toggle **Expand Issue Changelog** to get a list of updates to every issue in the Issues stream. If the toggle is off, the changelog will not be pulled. | ||
| 10. Toggle **Render Issue Fields** to additionally return field values rendered in HTML format in the Issues stream. Issue fields will always be returned in JSON format. | ||
| 11. Toggle **Enable Experimental Streams** to enable syncing for undocumented internal JIRA API endpoints and may stop working if those enpoints undergo major changes. Currently, this only applies to the PullRequests stream. | ||
| 10. Click **Set up source** | ||
|
|
||
| For detailed information on supported sync modes, supported streams, performance considerations, refer to the full documentation for [JIRA](https://docs.airbyte.com/integrations/sources/jira). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
why was this removed from here? Seems useful to have
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It still exists! It was just duplicated twice so I removed the first instance of it. It is now located above the Supported Streams but under the Setup Guide.