Skip to main content

async-amazon-ads-api-v1

PyPI version Python versions License: MIT

纯异步 Amazon Ads API 客户端。PyPI 安装名为 async-amazon-ads-api-v1,导入名为 ads_api。统一覆盖 v0 与 v1(SP、SB、SD、DSP、ST、SP Global、Accounts、Reporting、Ads Data Manager、Exports 等)。

Installation

pip install async-amazon-ads-api-v1
# 或
uv add async-amazon-ads-api-v1

Redis 缓存支持:

pip install "async-amazon-ads-api-v1[redis]"
# 或
uv add "async-amazon-ads-api-v1[redis]"

Quick Start

所有 API 方法仅接受 Pydantic model 实例,不支持 dict。默认 mode="dict",需要模型对象时传 mode="pydantic"。

使用 Access Token

import asyncio

from ads_api import AdsClient, AmazonAdsConfig, Region
from ads_api.models.v1.campaigns.sp import SPQueryCampaignRequest


async def main() -> None:
    config = AmazonAdsConfig(
        access_token="your-access-token",
        client_id="your-client-id",
        region=Region.NA,
    )
    body = SPQueryCampaignRequest(
        adProductFilter={"include": ["SPONSORED_PRODUCTS"]},
        stateFilter={"include": ["ENABLED"]},
    )

    async with AdsClient(config) as ads:
        resp = await ads.v1.sp.campaigns.query_campaign(body)
        print(resp)


asyncio.run(main())

使用 Refresh Token(自动续期)

import asyncio

from ads_api import AdsClient, AmazonAdsConfig, Region
from ads_api.models.v1.campaigns.sp import SPQueryCampaignRequest


async def main() -> None:
    config = AmazonAdsConfig(
        client_id="your-client-id",
        refresh_token="your-refresh-token",
        client_secret="your-client-secret",
        region=Region.NA,
    )
    body = SPQueryCampaignRequest(
        adProductFilter={"include": ["SPONSORED_PRODUCTS"]},
        stateFilter={"include": ["ENABLED"]},
    )

    async with AdsClient(config) as ads:
        resp = await ads.v1.sp.campaigns.query_campaign(body, mode="pydantic")
        print(resp.model_dump_json(indent=2))


asyncio.run(main())

Token Management

SDK 内置 OAuth token 生命周期管理。提供 refresh_token 与 client_secret 后会自动续期;缓存按字段推断:

from ads_api import AmazonAdsConfig, Region

# 自动续期,不使用磁盘 / Redis 缓存
config = AmazonAdsConfig(
    client_id="your-client-id",
    client_secret="your-client-secret",
    refresh_token="your-refresh-token",
    region=Region.NA,
)

# 文件缓存
config = AmazonAdsConfig(
    client_id="your-client-id",
    client_secret="your-client-secret",
    refresh_token="your-refresh-token",
    region=Region.NA,
    token_cache_dir="~/.cache/ads_api",
)

# Redis 缓存
config = AmazonAdsConfig(
    client_id="your-client-id",
    client_secret="your-client-secret",
    refresh_token="your-refresh-token",
    region=Region.NA,
    redis_url="redis://localhost:6379",
)

API 入口

async with AdsClient(config) as ads:
    # v1
    await ads.v1.sp.campaigns.query_campaign(body)
    await ads.v1.sb.campaigns.query_campaign(body)
    await ads.v1.sd.campaigns.query_campaign(body)
    await ads.v1.selling_accounts.query_selling_account(body)
    await ads.v1.reports.create_report(body)

    # v0
    await ads.v0.accounts.profiles.list_profiles()
    await ads.v0.portfolios.list_portfolios()
    await ads.v0.sp_v3.campaigns.create_sponsored_products_campaigns(body)
    await ads.v0.sb_v4.budget_rules.create_budget_rules_for_sb_campaigns(body)
    await ads.v0.sd.creatives.create_creatives(body)

Login with Amazon (LWA) OAuth 支持

内置轻量高效的异步 OAuthClient,支持生成授权跳转 URL、授权码换取 Token、刷新 Token 与获取 LWA 用户档案:

from ads_api import AdsClient, OAuthClient, Region

oauth = OAuthClient(
    client_id="your-client-id",
    client_secret="your-client-secret",
    scope="advertising::campaign_management",
    redirect_uri="https://app.com/callback",
    region=Region.NA,
)

# 1. 生成带 state 防重放的授权 URL
auth_url, state = oauth.get_authorization_url()

# 2. 换取 Token 并拉起 AdsClient
async with oauth:
    tokens = await oauth.exchange_code_for_tokens(code)
    config = oauth.create_config(tokens, profile_id="123456789")
    async with AdsClient(config) as ads:
        resp = await ads.v1.sp.campaigns.query_campaign(body)

License

MIT

Metadata

Release files for async-amazon-ads-api-v1 0.12.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for async-amazon-ads-api-v1 0.12.0
File Size Uploaded Provenance Actions
async_amazon_ads_api_v1-0.12.0.tar.gz 414.4 kB With provenance Details for async_amazon_ads_api_v1-0.12.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for async-amazon-ads-api-v1 0.12.0
File Interpreter ABI Platform Actions
async_amazon_ads_api_v1-0.12.0-py3-none-any.whl Python 3 none any Details for async_amazon_ads_api_v1-0.12.0-py3-none-any.whl

Total release size: 1.1 MB

Release files / async_amazon_ads_api_v1-0.12.0.tar.gz

Download URL async_amazon_ads_api_v1-0.12.0.tar.gz
Size 414.4 kB
Tags Source
SHA-256 checksum
How to use checksums
39fef7fa79be4fc11a479c47a1e13c28456794bd15a8b0df5c11ffa14484d6f1
BLAKE2b-256 checksum
How to use checksums
a03951524eb7d9f70eb8d491fb8b16f74b67a6d41b8aabbcad0826c580d9eaf0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / async_amazon_ads_api_v1-0.12.0-py3-none-any.whl

Download URL async_amazon_ads_api_v1-0.12.0-py3-none-any.whl
Size 664.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8822bd3fec50d88c60b43eb0ab975f4d8fd32d29d8e5c30c9851ec95d5f06e9f
BLAKE2b-256 checksum
How to use checksums
e4cf59a9ffeeaf4fa81508bd4c4a87298009910cec74649208be636d670cc9f9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for async-amazon-ads-api-v1 0.12.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for async_amazon_ads_api_v1-0.12.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.12.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page