google-cloud-channel Python 客户端实战:用 Cloud Channel API 完成转售商客户、SKU 与授权管理

原创2026-10-10 20:36:481,375 阅读

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+ 环境中直接运行验证。

登录后查看全文
context-hub