diff --git a/README.md b/README.md index 9347a0f..9334c49 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Python SDK for integrating Databricks with The Trade Desk Data API. Supports Fir - [Initial Setup](#initial-setup) - [SDK Example Usage](#sdk-example-usage) - [Authentication](#authentication) -- [Available Resources and Operations](#available-resources-and-operations) +- [Supported Data API Endpoints](#supported-data-api-endpoints) - [Error Handling](#error-handling) - [Server Selection](#server-selection) - [Custom HTTP Client](#custom-http-client) @@ -177,6 +177,8 @@ client.batch_process( All API calls require a TTD auth token passed at client creation time. +> **Note:** The SDK does not support `TtdSignature` based authentication. Refer to [OpenTTD](https://open.thetradedesk.com/advertiser/docsApp/Foundations/resources/doc/PlatformAuthentication) for instructions on how to create your `TTD-Auth` API token (select `Data API` as the `Application`). + ### Factory Method (recommended for notebooks) ```python @@ -212,9 +214,18 @@ client = TtdDatabricksClient( --- -## Available Resources and Operations +## Supported Data API Endpoints + +Each Data API endpoint is represented by a context dataclass that configures the API call. The following table lists the supported Data API endpoints, their corresponding SDK contexts, and OpenTTD documentation. -Each endpoint is represented by a context dataclass that configures the API call. +| Data API Endpoint | Context | OpenTTD API Documentation | +|---|---|---| +| `POST /data/advertiser` | `AdvertiserContext` | [OpenTTD Documentation](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-data-advertiser-firstparty)
[OpenTTD Documentation (External Provider)](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-advertiser-external) | +| `POST /data/thirdparty` | `ThirdPartyContext` | [OpenTTD Documentation](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-thirdparty) | +| `POST /providerapi/offlineconversion` | `OfflineConversionContext` | [OpenTTD Documentation](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-providerapi-offlineconversion) | +| `POST /data/deletion-optout/advertiser` | `DeletionOptOutAdvertiserContext` | [OpenTTD Documentation](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-data-deletion-optout-advertiser)
[OpenTTD Documentation (External Provider)](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-advertiser-external) | +| `POST /data/deletion-optout/thirdparty` | `DeletionOptOutThirdPartyContext` | [OpenTTD Documentation ](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-thirdparty) | +| `POST /data/deletion-optout/merchant` | `DeletionOptOutMerchantContext` | [OpenTTD Documentation](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/retail/doc/post-data-deletion-optout-merchant) | ### First-Party Data — `/data/advertiser` @@ -229,7 +240,7 @@ context = AdvertiserContext( ) ``` -The schema for `TTDEndpoint.ADVERTISER` is defined in [advertiser.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/advertiser.py). Check out the [Inspecting Schemas](https://github.com/thetradedesk/ttd-databricks-python/blob/main/README.md#inspecting-schemas) section to list required and optional columns and use the helper functions to validate your DataFrame before submitting. +The input schema for `TTDEndpoint.ADVERTISER` is defined in [advertiser.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/advertiser.py). See the [Inspecting Schemas](#inspecting-schemas) section for helper functions to view columns and validate your DataFrame. --- @@ -246,7 +257,7 @@ context = ThirdPartyContext( ) ``` -The schema for `TTDEndpoint.THIRD_PARTY` is defined in [third_party.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/third_party.py). Check out the [Inspecting Schemas](https://github.com/thetradedesk/ttd-databricks-python/blob/main/README.md#inspecting-schemas) section to list required and optional columns and use the helper functions to validate your DataFrame before submitting. +The input schema for `TTDEndpoint.THIRD_PARTY` is defined in [third_party.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/third_party.py). See the [Inspecting Schemas](#inspecting-schemas) section for helper functions to view columns and validate your DataFrame. --- @@ -261,7 +272,7 @@ context = OfflineConversionContext( ) ``` -The schema for `TTDEndpoint.OFFLINE_CONVERSION` is defined in [offline_conversion.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/offline_conversion.py). Check out the [Inspecting Schemas](https://github.com/thetradedesk/ttd-databricks-python/blob/main/README.md#inspecting-schemas) section to list required and optional columns and use the helper functions to validate your DataFrame before submitting. +The input schema for `TTDEndpoint.OFFLINE_CONVERSION` is defined in [offline_conversion.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/offline_conversion.py). See the [Inspecting Schemas](#inspecting-schemas) section for helper functions to view columns and validate your DataFrame. --- @@ -282,7 +293,7 @@ context = DeletionOptOutAdvertiserContext( ) ``` -The schema for `TTDEndpoint.DELETION_OPTOUT_ADVERTISER` is defined in [deletion_optout_advertiser.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/deletion_optout_advertiser.py). Check out the [Inspecting Schemas](https://github.com/thetradedesk/ttd-databricks-python/blob/main/README.md#inspecting-schemas) section to list required and optional columns and use the helper functions to validate your DataFrame before submitting. +The input schema for `TTDEndpoint.DELETION_OPTOUT_ADVERTISER` is defined in [deletion_optout_advertiser.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/deletion_optout_advertiser.py). See the [Inspecting Schemas](#inspecting-schemas) section for helper functions to view columns and validate your DataFrame. --- @@ -300,7 +311,7 @@ context = DeletionOptOutThirdPartyContext( ) ``` -The schema for `TTDEndpoint.DELETION_OPTOUT_THIRDPARTY` is defined in [deletion_optout_thirdparty.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/deletion_optout_thirdparty.py). Check out the [Inspecting Schemas](https://github.com/thetradedesk/ttd-databricks-python/blob/main/README.md#inspecting-schemas) section to list required and optional columns and use the helper functions to validate your DataFrame before submitting. +The input schema for `TTDEndpoint.DELETION_OPTOUT_THIRDPARTY` is defined in [deletion_optout_thirdparty.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/deletion_optout_thirdparty.py). See the [Inspecting Schemas](#inspecting-schemas) section for helper functions to view columns and validate your DataFrame. --- @@ -317,7 +328,7 @@ context = DeletionOptOutMerchantContext( ) ``` -The schema for `TTDEndpoint.DELETION_OPTOUT_MERCHANT` is defined in [deletion_optout_merchant.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/deletion_optout_merchant.py). Check out the [Inspecting Schemas](https://github.com/thetradedesk/ttd-databricks-python/blob/main/README.md#inspecting-schemas) section to list required and optional columns and use the helper functions to validate your DataFrame before submitting. +The input schema for `TTDEndpoint.DELETION_OPTOUT_MERCHANT` is defined in [deletion_optout_merchant.py](https://github.com/thetradedesk/ttd-databricks-python/blob/main/ttd_databricks_python/ttd_databricks/schemas/deletion_optout_merchant.py). See the [Inspecting Schemas](#inspecting-schemas) section for helper functions to view columns and validate your DataFrame. --- @@ -329,7 +340,9 @@ Retrieve the full input schema for an endpoint: from ttd_databricks_python.ttd_databricks import TTDEndpoint, get_ttd_input_schema schema = get_ttd_input_schema(TTDEndpoint.ADVERTISER) -print(schema.treeString()) + +for field in input_schema.fields: + print(f" {field.name}: {field.dataType.simpleString()} (nullable={field.nullable})") ``` Get just the required column names (useful for DataFrame preparation): diff --git a/example_notebook/TTD Connector Data SDK Example Notebook.ipynb b/example_notebook/TTD Connector Data SDK Example Notebook.ipynb index 29b34a6..4f1c123 100644 --- a/example_notebook/TTD Connector Data SDK Example Notebook.ipynb +++ b/example_notebook/TTD Connector Data SDK Example Notebook.ipynb @@ -37,7 +37,9 @@ "In production, retrieve secrets from Databricks Secrets:\n", "```python\n", "api_token = dbutils.secrets.get(scope=\"ttd\", key=\"api-token\")\n", - "```" + "```\n", + "\n", + "> **Note:** The SDK does not support `TtdSignature` based authentication. Refer to [OpenTTD](https://open.thetradedesk.com/advertiser/docsApp/Foundations/resources/doc/PlatformAuthentication) for instructions on how to create your `TTD-Auth` API token (select `Data API` as the `Application`)." ] }, { @@ -114,14 +116,14 @@ "\n", "For more information on the meaning of particular fields and supported data types supported per endpoint refer to the following table:\n", "\n", - "| Endpoint | Context | Data API | Documentation |\n", + "| Endpoint | Context | Data API | OpenTTD API Documentation |\n", "|---|---|---|---|\n", - "| Advertiser | `AdvertiserContext` | `POST /data/advertiser` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-advertiser-external) |\n", - "| Third Party | `ThirdPartyContext` | `POST /data/thirdparty` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-thirdparty) |\n", - "| Offline Conversion | `OfflineConversionContext` | `POST /providerapi/offlineconversion` | [OpenTTD](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-providerapi-offlineconversion) |\n", - "| Deletion / Opt-Out — Advertiser | `DeletionOptOutAdvertiserContext` | `POST /data/deletion-optout/advertiser` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-advertiser-external) |\n", - "| Deletion / Opt-Out — Third Party | `DeletionOptOutThirdPartyContext` | `POST /data/deletion-optout/thirdparty` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-thirdparty) |\n", - "| Deletion / Opt-Out — Merchant | `DeletionOptOutMerchantContext` | `POST /data/deletion-optout/merchant` | [OpenTTD](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/retail/doc/post-data-deletion-optout-merchant) |" + "| Advertiser | `AdvertiserContext` | `POST /data/advertiser` | [OpenTTD Documentation](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-data-advertiser-firstparty)
[OpenTTD Documentation (External Provider)](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-advertiser-external) |\n", + "| Third Party | `ThirdPartyContext` | `POST /data/thirdparty` | [OpenTTD Documentation](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-thirdparty) |\n", + "| Offline Conversion | `OfflineConversionContext` | `POST /providerapi/offlineconversion` | [OpenTTD Documentation](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-providerapi-offlineconversion) |\n", + "| Deletion / Opt-Out — Advertiser | `DeletionOptOutAdvertiserContext` | `POST /data/deletion-optout/advertiser` | [OpenTTD Documentation](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-data-deletion-optout-advertiser)
[OpenTTD Documentation (External Provider)](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-advertiser-external) |\n", + "| Deletion / Opt-Out — Third Party | `DeletionOptOutThirdPartyContext` | `POST /data/deletion-optout/thirdparty` | [OpenTTD Documentation](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-thirdparty) |\n", + "| Deletion / Opt-Out — Merchant | `DeletionOptOutMerchantContext` | `POST /data/deletion-optout/merchant` | [OpenTTD Documentation](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/retail/doc/post-data-deletion-optout-merchant) |" ] }, { @@ -331,4 +333,4 @@ }, "nbformat": 4, "nbformat_minor": 4 -} +} \ No newline at end of file