python-amazon-ad-api 1.1.5__tar.gz → 1.1.7__tar.gz

{python_amazon_ad_api-1.1.5 → python_amazon_ad_api-1.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.1.5
+Version: 1.1.7
 Summary: Python wrapper for the Amazon Advertising API
 Home-page: https://github.com/denisneuf/python-amazon-ad-api
 Author: Daniel Alvaro

{python_amazon_ad_api-1.1.5 → python_amazon_ad_api-1.1.7}/ad_api/api/sb/__init__.py

@@ -23,6 +23,7 @@ from .themes import Themes
 from .budget_rules import BudgetRules
 from .optimization_rules import OptimizationRules
 from .targeting_categories import TargetingCategories
+from .migration import Migration
 
 __all__ = [
     "Brands",
@@ -50,4 +51,5 @@ __all__ = [
     "BudgetRules",
     "OptimizationRules",
     "TargetingCategories",
+    "Migration",
 ]

{python_amazon_ad_api-1.1.5 → python_amazon_ad_api-1.1.7}/ad_api/api/sb/ad_creatives_v4.py

@@ -128,6 +128,92 @@ class AdCreativesV4(Client):
 
         return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
 
+    @sp_endpoint('/sb/ads/creatives/autoCollection', method='POST')
+    def create_auto_collection_ad_creative(self, version: int = 4, **kwargs) -> ApiResponse:
+        """
+        Creates a new version of an auto collection creative for an existing ad.
+
+        Request Body [Required]
+            | **ads** (array): [required] One entry per ad.
+                | **adId** (string): [required] Sponsored Brands ad identifier.
+                | **creative** ({}): [required]
+                    | **brandName** (string): [required]
+                    | **brandLogoAssetID** (string): [optional]
+                    | **brandLogoCrop** ({}): [optional] ``top``, ``left``,
+                      ``width`` and ``height``.
+                    | **asinExclusions** (array of string): [optional]
+
+        Returns:
+            | ApiResponse
+
+        .. note::
+            This route takes ``application/vnd.sbadresource.v4+json``, the same
+            media type as the ads family, not the creative one.
+        """
+        json_version = 'application/vnd.sbadresource.v' + str(version) + "+json"
+        headers = {'Accept': json_version}
+
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
+
+    @sp_endpoint('/sb/ads/creatives/manualCollection', method='POST')
+    def create_manual_collection_ad_creative(self, version: int = 4, **kwargs) -> ApiResponse:
+        """
+        Creates a new version of a manual collection creative for an existing ad.
+
+        Request Body [Required]
+            | **ads** (array): [required] One entry per ad, each with ``adId``
+              and a ``creative`` block.
+
+        Returns:
+            | ApiResponse
+
+        .. note::
+            Also takes ``application/vnd.sbadresource.v4+json``.
+        """
+        json_version = 'application/vnd.sbadresource.v' + str(version) + "+json"
+        headers = {'Accept': json_version}
+
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
+
+    @sp_endpoint('/sb/ads/creatives/productCollectionExtended', method='POST')
+    @Utils.deprecated
+    def create_new_version_product_collection_extended_ad_creative(self, version: int = 4, **kwargs) -> ApiResponse:
+        """
+        Creates a new version of an extended product collection creative.
+
+        This route is flagged deprecated in the 4.0 contract. It still answers on
+        the live service, which is why it stays available, but new integrations
+        should use ``create_auto_collection_ad_creative`` or
+        ``create_manual_collection_ad_creative``.
+
+        Request Body [Required]
+            | **adId** (string): [required] Sponsored Brands ad identifier.
+            | **creative** ({}): [required]
+                | **asins** (array of string): [required]
+                | **brandName** (string): [required]
+                | **brandLogoAssetId** (string): [required]
+                | **headline** (string): [required]
+                | **landingPage** ({}): [optional] ``type``, ``url`` or ``asins``.
+                | **brandLogoCrop** ({}): [optional] ``top``, ``left``,
+                  ``width`` and ``height``.
+                | **customImages** (array): [optional] Each with ``assetId``,
+                  ``url`` and a ``crop``.
+                | **consentToTranslate** (boolean): [optional]
+
+        Returns:
+            | ApiResponse
+
+        .. note::
+            Unlike its siblings this route takes a single ``adId`` and
+            ``creative``, not an ``ads`` list, and it uses
+            ``application/vnd.sbAdCreativeResource.v4+json``. An empty body names
+            both required members.
+        """
+        json_version = 'application/vnd.sbAdCreativeResource.v' + str(version) + "+json"
+        headers = {'Accept': json_version}
+
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
+
     @sp_endpoint('/sb/ads/creatives/list', method='POST')
     def list_ad_creatives(self, version: int = 4, **kwargs) -> ApiResponse:
         """

{python_amazon_ad_api-1.1.5 → python_amazon_ad_api-1.1.7}/ad_api/api/sb/ads_v4.py

@@ -165,6 +165,85 @@ class AdsV4(Client):
 
         return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
 
+    @sp_endpoint('/sb/v4/ads/autoCollection', method='POST')
+    def create_auto_collection_ads(self, version: int = 4, **kwargs) -> ApiResponse:
+        """
+        Creates Sponsored Brands auto collection ads.
+
+        Request Body [Required]
+            | **ads** (array): [required] One entry per ad.
+                | **adGroupId** (string): [required] Ad group the ad belongs to.
+                | **name** (string): [required] Ad name.
+                | **state** (string): [required] ``ENABLED``, ``PAUSED`` or
+                  ``ARCHIVED``.
+                | **creative** ({}): [required]
+                    | **brandName** (string): [required]
+                    | **brandLogoAssetID** (string): [optional]
+                    | **brandLogoCrop** ({}): [optional] ``top``, ``left``,
+                      ``width`` and ``height``.
+                    | **asinExclusions** (array of string): [optional]
+
+        Returns:
+            | ApiResponse
+
+        .. note::
+            An empty body answers ``400 INVALID_ARGUMENT`` with
+            *"Ad list cannot be empty."*, and ``application/json`` answers
+            ``404 Could not find resource``, so the versioned media type is what
+            routes the call.
+        """
+        json_version = 'application/vnd.sbadresource.v' + str(version) + "+json"
+        headers = {'Accept': json_version}
+
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
+
+    @sp_endpoint('/sb/v4/ads/manualCollection', method='POST')
+    def create_manual_collection_ads(self, version: int = 4, **kwargs) -> ApiResponse:
+        """
+        Creates Sponsored Brands manual collection ads.
+
+        Request Body [Required]
+            | **ads** (array): [required] One entry per ad, each with
+              ``adGroupId``, ``name``, ``state`` and a ``creative`` block.
+
+        Returns:
+            | ApiResponse
+
+        .. note::
+            An empty body answers ``400 INVALID_ARGUMENT`` with
+            *"Ad list cannot be empty."*
+        """
+        json_version = 'application/vnd.sbadresource.v' + str(version) + "+json"
+        headers = {'Accept': json_version}
+
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
+
+    @sp_endpoint('/sb/v4/ads/productCollectionExtended', method='POST')
+    @Utils.deprecated
+    def create_product_collection_extended_ads(self, version: int = 4, **kwargs) -> ApiResponse:
+        """
+        Creates Sponsored Brands extended product collection ads.
+
+        This route is flagged deprecated in the 4.0 contract, together with the
+        creative side of the same name. It still answers on the live service,
+        which is why it stays available, but new integrations should use
+        ``create_auto_collection_ads`` or ``create_manual_collection_ads``.
+
+        Request Body [Required]
+            | **ads** (array): [required] One entry per ad.
+
+        Returns:
+            | ApiResponse
+
+        .. note::
+            An empty body answers ``400 INVALID_ARGUMENT`` with
+            *"Ad list cannot be empty."*
+        """
+        json_version = 'application/vnd.sbadresource.v' + str(version) + "+json"
+        headers = {'Accept': json_version}
+
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
+
     @sp_endpoint('/sb/v4/ads/delete', method='POST')
     def delete_ads(self, version: int = 4, **kwargs) -> ApiResponse:
         """

python_amazon_ad_api-1.1.7/ad_api/api/sb/migration.py

@@ -0,0 +1,154 @@
+from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
+
+
+class Migration(Client):
+    """Sponsored Brands legacy campaign migration from 3.0 to 4.0.
+
+    Documentation: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/4-0/openapi
+
+    Two media types live in this family, both versioned and both required:
+
+    ========================================  ==========================================================
+    Route                                      Media type
+    ========================================  ==========================================================
+    ``/sb/v4/legacyCampaigns/*``               ``vnd.SponsoredBrands.SponsoredBrandsMigrationApi.v4``
+    ``/sb/v4/migrations/list``                 ``vnd.sbAdMigration.v4``
+    ========================================  ==========================================================
+
+    .. warning::
+        ``list_migrations`` answers ``404 Could not find resource`` when sent
+        ``application/json``, the same behaviour already recorded for forecasts,
+        budget recommendations and optimization rules. Amazon routes on media
+        type; a wrong one reads exactly like a missing route.
+
+    .. note::
+        ``migration_job_status`` and ``migration_job_results`` answer ``500
+        INTERNAL_ERROR`` for a job identifier that does not exist, instead of a
+        400 or a 404. The routes are live; the service trips over an unknown id.
+    """
+
+    _MEDIA_LEGACY = ('application/vnd.SponsoredBrands.'
+                     'SponsoredBrandsMigrationApi.v4+json')
+    _MEDIA_ADMIG = 'application/vnd.sbAdMigration.v4+json'
+
+    @sp_endpoint('/sb/v4/legacyCampaigns/migrationJob', method='POST')
+    def start_migration_job(self, campaignIds, enableThemeTargeting, **kwargs) -> ApiResponse:
+        """
+        Starts a migration job for 3.0 campaigns.
+
+        Request Body [Required]
+            | **campaignIds** (array of string): [required] Campaigns to migrate.
+            | **enableThemeTargeting** (boolean): [required] Carry theme targets
+              into the new campaigns.
+            | **isStagedMigration** (boolean): [optional]
+            | **newCampaignState** (string): [optional] State for the migrated
+              campaigns.
+            | **brandEntityId** (string): [optional]
+
+        Returns:
+            | ApiResponse, ``200``.
+
+        .. warning::
+            **This changes the account.** It starts a real migration of 3.0
+            campaigns into 4.0, which is not something a probe or a retry should
+            trigger by accident. Because of that it was never exercised here: the
+            shape comes from the contract only.
+
+        .. note::
+            Do not treat a timeout as a failed migration. The job may be running;
+            check ``migration_job_status`` before trying again.
+        """
+        body = {'campaignIds': campaignIds, 'enableThemeTargeting': enableThemeTargeting}
+        for key in ('isStagedMigration', 'newCampaignState', 'brandEntityId'):
+            if key in kwargs:
+                body[key] = kwargs.pop(key)
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(body, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_LEGACY,
+                                                     'Content-Type': self._MEDIA_LEGACY})
+
+    @sp_endpoint('/sb/v4/legacyCampaigns/migrationJob/status', method='POST')
+    def migration_job_status(self, jobId, **kwargs) -> ApiResponse:
+        """
+        Gets the status of a migration job.
+
+        Request Body [Required]
+            | **jobId** (string): [required]
+
+        Returns:
+            | ApiResponse, ``200``.
+
+        .. note::
+            An unknown ``jobId`` answers ``500 INTERNAL_ERROR`` rather than a
+            business error. Not a sign that the route is missing.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body({'jobId': jobId}, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_LEGACY,
+                                                     'Content-Type': self._MEDIA_LEGACY})
+
+    @sp_endpoint('/sb/v4/legacyCampaigns/migrationJob/results', method='POST')
+    def migration_job_results(self, jobId, **kwargs) -> ApiResponse:
+        """
+        Lists the per-campaign results of a migration job.
+
+        Request Body [Required]
+            | **jobId** (string): [required]
+            | **nextToken** (string): [optional]
+
+        Returns:
+            | ApiResponse, ``200``.
+
+        .. note::
+            An unknown ``jobId`` answers ``500 INTERNAL_ERROR``, as with the
+            status route.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body({'jobId': jobId}, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_LEGACY,
+                                                     'Content-Type': self._MEDIA_LEGACY})
+
+    @sp_endpoint('/sb/v4/legacyCampaigns/overallMigrationResults', method='POST')
+    def overall_migration_results(self, **kwargs) -> ApiResponse:
+        """
+        Lists every campaign migration result for the advertiser.
+
+        Request Body [Optional]
+            | **nextToken** (string): [optional]
+
+        Returns:
+            | ApiResponse, ``200``. With nothing migrated yet the service answers
+            an empty object rather than a list, so do not assume a ``migrations``
+            key is always present.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body(kwargs.pop('body', {}), False),
+                             params=kwargs, headers={'Accept': self._MEDIA_LEGACY,
+                                                     'Content-Type': self._MEDIA_LEGACY})
+
+    @sp_endpoint('/sb/v4/migrations/list', method='POST')
+    def list_migrations(self, **kwargs) -> ApiResponse:
+        """
+        Lists ad migrations.
+
+        Request Body [Optional]
+            | **adGroupIdFilter** ({}): ``include``, a list of ad group ids.
+            | **adIdFilter** ({}): ``include``, a list of ad ids.
+            | **campaignIdFilter** ({}): ``include``, a list of campaign ids.
+            | **adStateFilter** ({}): ``include`` with ``ENABLED``, ``PAUSED``
+              or ``ARCHIVED``.
+            | **migrationStatusFilter** ({}): ``include`` with ``ACCEPTED``,
+              ``ELIGIBLE``, ``MIGRATED`` or ``MIGRATION_FAILED``.
+            | **maxResults** (number): Page size.
+            | **nextToken** (string): Pagination token.
+
+        Returns:
+            | ApiResponse, ``200``, with ``migrations`` and ``totalCount``.
+
+        Example::
+
+            {"migrations": [], "totalCount": 0}
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body(kwargs.pop('body', {}), False),
+                             params=kwargs, headers={'Accept': self._MEDIA_ADMIG,
+                                                     'Content-Type': self._MEDIA_ADMIG})

python_amazon_ad_api-1.1.7/ad_api/version.py

@@ -0,0 +1 @@
+__version__ = "1.1.7"

{python_amazon_ad_api-1.1.5 → python_amazon_ad_api-1.1.7}/python_amazon_ad_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.1.5
+Version: 1.1.7
 Summary: Python wrapper for the Amazon Advertising API
 Home-page: https://github.com/denisneuf/python-amazon-ad-api
 Author: Daniel Alvaro

{python_amazon_ad_api-1.1.5 → python_amazon_ad_api-1.1.7}/python_amazon_ad_api.egg-info/SOURCES.txt

@@ -45,6 +45,7 @@ ad_api/api/sb/keywords.py
 ad_api/api/sb/keywords_recommendations.py
 ad_api/api/sb/landing_page_asins.py
 ad_api/api/sb/media.py
+ad_api/api/sb/migration.py
 ad_api/api/sb/negative_keywords.py
 ad_api/api/sb/negative_product_targeting.py
 ad_api/api/sb/optimization_rules.py

{python_amazon_ad_api-1.1.5 → python_amazon_ad_api-1.1.7}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = python-amazon-ad-api
-version = 1.1.5
+version = 1.1.7
 author = Daniel Alvaro
 author_email = denisneuf@hotmail.com
 description = Python wrapper for the Amazon Advertising API

{python_amazon_ad_api-1.1.5 → python_amazon_ad_api-1.1.7}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup
 
 setup(
     name='python-amazon-ad-api',
-    version='1.1.5',
+    version='1.1.7',
     install_requires=[
         "requests>=2.27.1,<2.35.0",
         "six>=1.16,<1.18",

python_amazon_ad_api-1.1.5/ad_api/version.py

@@ -1 +0,0 @@
-__version__ = "1.1.5"