Merge pull request #57 from twistedFantasy/main

Support Amazon DSP API - Reports entity

Author: denisneuf

README.md

@@ -305,6 +305,9 @@ curl \
 * Bid Recommendations
 * Creatives
 
+### Modules Available DSP
+
+* Reports
 
 ### Simple Example Usage Campaigns with Credentials
 

ad_api/api/dsp/__init__.py

@@ -0,0 +1,11 @@
+from .reports import Reports
+from .client import DspClient
+from .access_token_client import DspAccessTokenClient
+from .credential_provider import DspCredentialProvider
+
+__all__ = [
+    "Reports",
+    "DspClient",
+    "DspAccessTokenClient",
+    "DspCredentialProvider"
+]

ad_api/api/dsp/access_token_client.py

@@ -0,0 +1,6 @@
+from ad_api.api.dsp.credential_provider import DspCredentialProvider
+from ad_api.auth.access_token_client import AccessTokenClient
+
+
+class DspAccessTokenClient(AccessTokenClient):
+    credential_provider_class = DspCredentialProvider

ad_api/api/dsp/client.py

@@ -0,0 +1,19 @@
+from ad_api.base import Client
+from ad_api.auth.credentials import BaseCredentials
+from ad_api.api.dsp.credential_provider import DspCredentialProvider
+from ad_api.api.dsp.access_token_client import DspAccessTokenClient
+
+
+class DspClient(Client):
+    access_token_client_class = DspAccessTokenClient
+    credentials_class = BaseCredentials
+    credential_provider_class = DspCredentialProvider
+
+    @property
+    def headers(self):
+        return {
+            'User-Agent': self.user_agent,
+            'Amazon-Advertising-API-ClientId': self.credentials.client_id,
+            'Authorization': 'Bearer %s' % self.auth.access_token,
+            'Content-Type': 'application/json',
+        }

ad_api/api/dsp/credential_provider.py

@@ -0,0 +1,15 @@
+from ad_api.base.config import BaseConfig
+from ad_api.base.credential_provider import CredentialProvider
+
+
+class DspCredentialProvider(CredentialProvider):
+    config_class = BaseConfig
+
+    def from_env(self):
+        account_data = dict(
+            refresh_token=self._get_env('AD_API_REFRESH_TOKEN'),
+            client_id=self._get_env('AD_API_CLIENT_ID'),
+            client_secret=self._get_env('AD_API_CLIENT_SECRET'),
+        )
+        self.credentials = self.config_class(**account_data)
+        return len(self.credentials.check_config()) == 0

ad_api/api/dsp/reports.py

@@ -0,0 +1,71 @@
+from ad_api.api.dsp.client import DspClient as Client
+from ad_api.base import sp_endpoint, fill_query_params, ApiResponse
+
+
+class Reports(Client):
+    """Amazon DSP Reports
+
+    Documentation: https://advertising.amazon.com/API/docs/en-us/dsp-reports-beta-3p/#/Reports
+
+    Amazon DSP is a demand-side platform (DSP) that enables advertisers to programmatically buy display, video, and audio ads both on and off Amazon. Using Amazon's DSP, you can reach audiences across the web on both Amazon sites and apps as well as through our publishing partners and third-party exchanges. Amazon DSP is available to both advertisers who sell products on Amazon and those who do not.
+    """
+
+    @sp_endpoint('/accounts/{}/dsp/reports', method='POST')
+    def post_report(self, dspAccountId, accept='application/vnd.dspcreatereports.v3+json', **kwargs) -> ApiResponse:
+        r"""
+        Request reports with performance metrics for DSP campaigns.
+
+        Request creation of a report that includes metrics about your Amazon DSP campaigns. Specify the type of report and the metrics you'd like to include. Note that the value specified for the dimensions field affects the metrics included in the report. See the dimensions field description for more information.
+
+        Keyword Args
+            | path **dspAccountId** (string): Account Identifier you use to access the DSP. This is your DSP Entity ID if you have access to all DSP advertisers within that entity, or your DSP Advertiser ID if you only have access to a specific advertiser ID. [required]
+
+        Request body
+            | **advertiserIds** (list > string): [optional] List of advertisers specified by identifier to include in the report. This should not be present if accountId is advertiser.
+            | **endDate** (string): [required] Date in yyyy-MM-dd format. The report contains only metrics generated on the specified date range between startDate and endDate. The maximum date range between startDate and endDate is 31 days. The endDate can be up to 90 days older from today.
+            | **format** (string): [optional] Enum: The report file format. [JSON]
+            | **orderIds** (list > string): [optional] List of orders specified by identifier to include in the report.
+            | **metrics** (list > string): [optional] Specify a list of metrics field names to include in the report. For example: ["impressions", "clickThroughs", "CTR", "eCPC", "totalCost", "eCPM"]. If no metric field names are specified, only the default fields and selected DIMENSION fields are included by default. Specifying default fields returns an error.
+            | **type** (string): [optional] Enum: The report type. [CAMPAIGN]
+            | **startDate** (string): [required] Date in yyyy-MM-dd format. The report contains only metrics generated on the specified date range between startDate and endDate. The maximum date range between startDate and endDate is 31 days. The startDate can be up to 90 days older from today.
+            | **dimensions** (list > string): [optional] List of dimensions to include in the report. Specify one or many comma-delimited strings of dimensions. For example: ["ORDER", "LINE_ITEM", "CREATIVE"]. Adding a dimension in this array determines the aggregation level of the report data and also adds the fields for that dimension in the report. If the list is null or empty, the aggregation of the report data is at ORDER level. The allowed values can be used together in this array as an allowed value in which case the report aggregation will be at the lowest aggregation level and the report will contain the fields for all the dimensions included in the report.
+            | **timeUnit** (string): [optional] Enum: Adding timeUnit determines the aggregation level (SUMMARY or DAILY) of the report data. If the timeUnit is null or empty, the aggregation of the report data is at the SUMMARY level and aggregated at the time period specified. DAILY timeUnit is not supported for AUDIENCE report type. The report will contain the fields based on timeUnit. [SUMMARY]
+
+        Returns:
+            ApiResponse
+        """
+        path = fill_query_params(kwargs.pop('path'), dspAccountId)
+        return self._request(path, data=kwargs.pop('body'), headers={'Accept': accept}, params=kwargs)
+
+    @sp_endpoint('/accounts/{}/dsp/reports/{}', method='GET')
+    def get_report(self, dspAccountId, reportId, accept='application/vnd.dspgetreports.v3+json', **kwargs) -> ApiResponse:
+        r"""
+        Gets a previously requested report specified by identifier.
+
+        Keyword Args
+            | path **dspAccountId** (string): Account Identifier for DSP. Please input DSP entity ID if you want to retrieve reports for a group of advertisers, or input DSP advertiser ID if you want to retrieve reports for a single advertiser. [required]
+            | path **reportId** (string): The identifier of the requested report. [required]
+
+        Returns:
+            ApiResponse
+        """
+        path = fill_query_params(kwargs.pop('path'), dspAccountId, reportId)
+        return self._request(path, headers={'Accept': accept}, params=kwargs)
+
+    def download_report(self, **kwargs) -> ApiResponse:
+        r"""
+        Downloads the report previously get report specified by location (this is not part of the official Amazon Advertising API, is a helper method to download the report). Take in mind that a direct download of location returned in get_report will return 401 - Unauthorized.
+
+        kwarg parameter **file** if not provided will take the default amazon name from path download (add a path with slash / if you want a specific folder, do not add extension as the return will provide the right extension based on format choosed if needed)
+
+        kwarg parameter **format** if not provided a format will return a url to download the report (this url has a expiration time)
+
+        Keyword Args
+            | **url** (string): The location obatined from get_report [required]
+            | **file** (string): The path to save the file if mode is download json, zip or gzip. [optional]
+            | **format** (string): The mode to download the report: data (list), raw, url, json, zip, gzip. Default (url) [optional]
+
+        Returns:
+            ApiResponse
+        """
+        return self._download(self, params=kwargs, headers={'User-Agent': self.user_agent})

ad_api/auth/access_token_client.py

@@ -1,5 +1,3 @@
-import json
-import os
 import requests
 import hashlib
 import logging
@@ -21,9 +19,9 @@ class AccessTokenClient(BaseClient):
     grant_type = 'refresh_token'
     path = '/auth/o2/token'
 
-    def __init__(self, account='default', credentials=None):
+    def __init__(self, account='default', credentials=None, credentials_class=Credentials):
         super().__init__(account, credentials)
-        self.cred = Credentials(self.credentials)
+        self.cred = credentials_class(self.credentials)
 
     def _request(self, url, data, headers):
         response = requests.post(url, data=data, headers=headers)
@@ -57,7 +55,6 @@ def get_auth(self) -> AccessTokenResponse:
             cache[cache_key] = access_token
         return AccessTokenResponse(**access_token)
 
-
     def authorize_auth_code(self, auth_code):
         request_url = self.scheme + self.host + self.path
         res = self._request(

ad_api/auth/credentials.py

@@ -1,8 +1,11 @@
-import os
-
-class Credentials:
+class BaseCredentials:
     def __init__(self, credentials):
         self.client_id = credentials.client_id
         self.client_secret = credentials.client_secret
         self.refresh_token = credentials.refresh_token
+
+
+class Credentials(BaseCredentials):
+    def __init__(self, credentials):
+        super().__init__(credentials)
         self.profile_id = credentials.profile_id

ad_api/base/base_client.py

@@ -1,17 +1,18 @@
-from ad_api.base.credential_provider import CredentialProvider
 import ad_api.version as vd
+from ad_api.base.credential_provider import CredentialProvider
+
 
 class BaseClient:
     scheme = 'https://'
     method = 'GET'
     content_type = 'application/x-www-form-urlencoded;charset=UTF-8'
     user_agent = 'python-ad-api'
-
+    credential_provider_class = CredentialProvider
 
     def __init__(self, account='default', credentials=None):
         try:
             version = vd.__version__
             self.user_agent += f'-{version}'
         except:
             pass
-        self.credentials = CredentialProvider(account, credentials).credentials
+        self.credentials = self.credential_provider_class(account, credentials).credentials

ad_api/base/client.py

@@ -1,12 +1,12 @@
 import json
-from datetime import datetime
 import logging
 from cachetools import TTLCache
 from requests import request
+from ad_api.auth.credentials import Credentials
 from ad_api.auth import AccessTokenClient, AccessTokenResponse
 from .api_response import ApiResponse
 from .base_client import BaseClient
-from .exceptions import get_exception_for_code, get_exception_for_content, AdvertisingApiBadRequestException
+from .exceptions import get_exception_for_content
 from .marketplaces import Marketplaces
 import sys
 import os
@@ -23,6 +23,8 @@
 
 
 class Client(BaseClient):
+    access_token_client_class = AccessTokenClient
+    credentials_class = Credentials
     grantless_scope = ''
 
     def __init__(
@@ -37,7 +39,9 @@ def __init__(
         super().__init__(account, credentials)
         self.endpoint = marketplace.endpoint
         self.debug = debug
-        self._auth = AccessTokenClient(account=account, credentials=credentials)
+        self._auth = self.access_token_client_class(
+            account=account, credentials=credentials, credentials_class=self.credentials_class
+        )
 
     @property
     def headers(self):