google-cloud-channel Python 客户端实战:用 Cloud Channel API 完成转售商客户、SKU 与授权管理
google-cloud-channel Python 客户端实战:用 Cloud Channel API 完成转售商客户、SKU 与授权管理
导读
google-cloud-channel 是 Google Cloud Channel API 的官方 Python 客户端,专为**云转售商(reseller)**场景设计:管理转售客户(customers)、浏览可采购的 SKU 与 Offer、以及查看客户名下的授权(entitlements)。如果你已经具备 Cloud Channel 转售访问权限,并希望从 Python 中直接调用 accounts/{account_id}、accounts/{account_id}/customers/{customer_id} 这类资源路径,本文就是一份可照抄的实战指南。读完本文,你将掌握包的安装与版本固定、ADC 认证初始化、五个最常用的核心工作流(增查客户、查询可购 SKU 与授权),以及异步客户端的使用方式。
本文档以 Context Hub 仓库中的 channel Python 文档 为骨架编写,对应包版本锁定为 1.26.0。
什么是 google-cloud-channel
google-cloud-channel 是 Google Cloud Channel API 的官方 Python 客户端,面向转售商业务流:
- 管理客户:创建、查询、列出转售客户;
- 浏览商品目录:查询某个客户可采购的 SKU 与 Offer;
- 查看授权:检查转售账户下客户名下的授权(entitlements)。
它的适用前提是:你的集成场景已经拥有 Cloud Channel 转售商访问权限,需要从 Python 中调用诸如 accounts/{account_id} 和 accounts/{account_id}/customers/{customer_id} 的资源路径。注意,这里使用的是完整资源名(resource name),而不是裸的账号 ID——这一点贯穿后续所有示例,也是最常见的出错点之一。
在 Context Hub 仓库中,该文档按 name: channel、languages: "python"、versions: "1.26.0" 等 frontmatter 元信息组织(见 DOC.md 元信息),属于仓库中语言特定、版本固定的 API 参考内容,编码 Agent 可以直接引用它来编写正确的调用代码。
安装与版本固定
转售业务对行为一致性敏感,建议把包版本固定到项目期望的版本:
python -m pip install "google-cloud-channel==1.26.0"
常见的包管理器替代写法:
uv add "google-cloud-channel==1.26.0"
poetry add "google-cloud-channel==1.26.0"
PyPI 上该包当前声明 Requires: Python >=3.7,如果你的项目运行环境低于 Python 3.7,需要先升级解释器再安装。
一个容易踩的导入坑:安装的包名是 google-cloud-channel,但 Python 中导入模块路径是 google.cloud.channel_v1(版本化 API 命名空间),而不是 google.cloud.channel。所有类型、请求与客户端都从 channel_v1 导入。
认证与初始化
使用 Application Default Credentials(ADC)
客户端底层使用 Google Application Default Credentials(ADC)完成认证,推荐在本地开发时用 gcloud 建立登录态:
gcloud auth application-default login
export GOOGLE_CLOUD_ACCOUNT_ID="1234567890"
GOOGLE_CLOUD_ACCOUNT_ID 是你的转售商账户 ID,后续所有请求都要用它拼出 accounts/{account_id} 资源名。
服务账号密钥兜底
在 CI/CD 或服务器环境中,可以用服务账号 JSON 密钥替代本地登录:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
export GOOGLE_CLOUD_ACCOUNT_ID="1234567890"
初始化客户端
import os
from google.cloud import channel_v1
ACCOUNT_ID = os.environ["GOOGLE_CLOUD_ACCOUNT_ID"]
ACCOUNT_NAME = f"accounts/{ACCOUNT_ID}"
client = channel_v1.CloudChannelServiceClient()
需要特别说明的初始化要点:
- 绝大多数请求需要你的转售商账户资源,形式为
accounts/{account_id}; - 客户级别的请求使用
accounts/{account_id}/customers/{customer_id}这样的完整名称; - 只有在需要直接操作凭据对象时才需要单独安装
google-auth,Cloud Channel 客户端本身在底层走 ADC,无需手动传入凭据; - 若需要覆盖端点或调整 mTLS 行为,生成的客户端支持标准 Google API 客户端选项与环境变量,如
GOOGLE_API_USE_MTLS_ENDPOINT和GOOGLE_API_USE_CLIENT_CERTIFICATE。
核心工作流
以下五个工作流覆盖转售商日常操作中最常用的场景,均基于 channel_v1.CloudChannelServiceClient。
列出客户(List Customers)
list_customers 以账户资源名为 parent,返回该转售账户下的客户迭代器:
import os
from google.cloud import channel_v1
account_name = f"accounts/{os.environ['GOOGLE_CLOUD_ACCOUNT_ID']}"
client = channel_v1.CloudChannelServiceClient()
request = channel_v1.ListCustomersRequest(parent=account_name)
for customer in client.list_customers(request=request):
print(customer.name, customer.org_display_name)
注意两点:parent 必须是 accounts/{account_id} 形式;返回值是分页迭代器,for 循环直接遍历即可,不需要手动处理分页 token。
获取单个客户(Get Customer)
get_customer 需要完整的客户资源名:
from google.cloud import channel_v1
client = channel_v1.CloudChannelServiceClient()
request = channel_v1.GetCustomerRequest(
name="accounts/1234567890/customers/C012abcde"
)
customer = client.get_customer(request=request)
print(customer.org_display_name)
这里的 name 必须是 accounts/{account_id}/customers/{customer_id} 的完整形态,C012abcde 这类 customer ID 不能单独传入。
创建客户(Create Customer)
create_customer 是五个工作流中字段要求最严格的:必须提供 Customer.org_display_name(显示名称)、Customer.org_postal_address(组织邮寄地址),并且在 Customer.domain(域名)与 Customer.cloud_identity_id(Cloud Identity ID)二者中至少提供其一:
import os
from google.cloud import channel_v1
from google.type.postal_address_pb2 import PostalAddress
account_name = f"accounts/{os.environ['GOOGLE_CLOUD_ACCOUNT_ID']}"
client = channel_v1.CloudChannelServiceClient()
request = channel_v1.CreateCustomerRequest(
parent=account_name,
customer=channel_v1.Customer(
org_display_name="Example Resold Customer",
domain="example.com",
org_postal_address=PostalAddress(
region_code="US",
postal_code="94043",
administrative_area="CA",
locality="Mountain View",
address_lines=["1600 Amphitheatre Parkway"],
),
),
)
customer = client.create_customer(request=request)
print(customer.name)
代码中 PostalAddress 来自 google.type.postal_address_pb2,常用字段包括:
region_code:ISO 3166-1 两位国家/地区代码(如US);postal_code:邮政编码(如94043);administrative_area:行政区/州(如CA);locality:城市/地区(如Mountain View);address_lines:地址行列表。
成功后返回的 customer.name 即为新客户的完整资源名,可用于后续的 SKU 查询与授权管理。
查询客户可采购的 SKU(List Purchasable SKUs)
list_purchasable_skus 用于查看某个客户当前可采购的 SKU。关键点:它接收的是完整的客户资源名,而不是账户级别的 parent——只传账户 ID 会不符合 API 期望:
from google.cloud import channel_v1
client = channel_v1.CloudChannelServiceClient()
request = channel_v1.ListPurchasableSkusRequest(
customer="accounts/1234567890/customers/C012abcde"
)
for sku in client.list_purchasable_skus(request=request):
print(sku.name)
这在业务上对应"为某位转售客户挑选可下单的商品",返回的 SKU 列表是面向该客户可见范围过滤后的结果。
查询客户的授权(List Entitlements)
list_entitlements 用于查看客户名下已有的授权(即已开通的服务),同样使用客户资源名作为 parent:
from google.cloud import channel_v1
client = channel_v1.CloudChannelServiceClient()
request = channel_v1.ListEntitlementsRequest(
parent="accounts/1234567890/customers/C012abcde"
)
for entitlement in client.list_entitlements(request=request):
print(entitlement.name)
它与 list_purchasable_skus 的区别在于视角:前者回答"这个客户已经开通了什么",后者回答"这个客户现在还能买什么",二者配合即可覆盖从选品到存量盘点的主要管理闭环。
异步用法
包同时暴露 CloudChannelServiceAsyncClient,资源名模式与请求类型与同步客户端完全一致,适合放在 asyncio 事件循环中使用:
import asyncio
import os
from google.cloud import channel_v1
async def main() -> None:
client = channel_v1.CloudChannelServiceAsyncClient()
request = channel_v1.ListCustomersRequest(
parent=f"accounts/{os.environ['GOOGLE_CLOUD_ACCOUNT_ID']}"
)
async for customer in client.list_customers(request=request):
print(customer.name)
asyncio.run(main())
异步客户端的用法差异只有两处:构造时使用 CloudChannelServiceAsyncClient,遍历结果时使用 async for。其余请求类型(ListCustomersRequest、GetCustomerRequest、CreateCustomerRequest 等)与资源名规则均可复用同步示例。
常见陷阱
综合官方文档与实战反馈,以下几点最容易出错:
- 包名与导入路径不一致:安装
google-cloud-channel,但导入必须写from google.cloud import channel_v1; - 裸 ID 与完整资源名的混用:API 期望完整资源名,请严格按照
accounts/{account_id}与accounts/{account_id}/customers/{customer_id}的格式传参,不要只传账号 ID 或 customer ID; create_customer字段要求严格:比一些旧博客描述的更严格,生成的请求文档明确要求组织显示名称、组织邮寄地址,以及domain或cloud_identity_id二者之一;list_purchasable_skus只接受客户资源名:它不接受账户级别的 parent,必须传accounts/{account_id}/customers/{customer_id};- 报告服务模块已弃用:PyPI 上的包 README 说明报告(report)服务模块在
1.20.0已弃用;需要报表类能力时,请改用 Cloud Channel Reports API 包,不要在弃用模块上新增依赖。
版本敏感说明
该客户端存在两处与版本相关的注意事项:
- PyPI 当前列表版本为
1.26.0,但官方latest文档树下的生成式参考页面 chrome 中仍显示1.25.0。如果调试时发现行为差异,请优先信任本机已安装的包版本,再去参考文档中核对生成的 API 表面; - 当前包元数据要求 Python
>=3.7。
也就是说,排查问题时应以实际安装的包为准(本项目文档锁定 1.26.0),官方文档树的版本显示可能存在滞后。
官方参考资源
如需进一步核对 API 细节,可以从以下官方渠道继续查阅(本文不再粘贴外部链接):
- PyPI 项目页:
google-cloud-channel的版本、依赖与 README 信息; - 包文档根目录:Google Cloud Python 客户端参考文档的
cloudchannel/latest文档树; - 关键类型参考:
CloudChannelServiceClient、ListCustomersRequest、CreateCustomerRequest、Customer、ListPurchasableSkusRequest、ListEntitlementsRequest在生成式参考页面中的字段说明; - REST API 总览:Google Cloud Channel API 的 REST 参考;
- ADC 配置文档:Google Cloud 的 Application Default Credentials 设置指南。
在 Context Hub 仓库中的定位
本文所依据的指南文件位于 content/google/docs/channel/python/DOC.md,frontmatter 记录了 versions: "1.26.0"、languages: "python"、updated-on: "2026-03-13" 等元信息,属于 Context Hub 提供的版本化、语言特定 API 文档体系。仓库 README.md 说明了这类文档的用途:让编码 Agent 直接获取经过整理的、按版本固定的 API 文档,避免在会话中遗忘所学内容。编码 Agent 可通过仓库 CLI 以 chub get 拉取对应语言的文档(详见 CLI Reference 与 Content Guide),并在 反馈与标注 机制下持续反馈文档质量。本文所有代码示例均可在安装了 google-cloud-channel==1.26.0、配置好 ADC 与 GOOGLE_CLOUD_ACCOUNT_ID 的 Python 3.7+ 环境中直接运行验证。