ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

python-docs-samples 实战:使用 Google Cloud Tasks 创建 HTTP 任务与 OIDC 认证任务

python-docs-samples 实战:使用 Google Cloud Tasks 创建 HTTP 任务与 OIDC 认证任务 示例工程【免费下载链接】python-docs-samplesCode samples used on cloud.google.com项目地址https://gitcode.com/GitHub_Trending/py/python-docs-samples点击查看免费下载导读本文围绕开源仓库 python-docs-samples 中的 cloud_tasks/snippets 示例目录系统讲解如何通过 Google Cloud Tasks 客户端库创建 HTTP 目标任务从环境准备、队列创建到使用命令行工具create_http_task.py与create_http_task_with_token.py提交任务再到结合源码剖析任务对象构造、调度时间与执行截止时间、OIDC 令牌认证等底层实现细节。读完本文你将掌握在 Python 项目中创建 Cloud Tasks HTTP 任务、配置安全认证、管理队列并编写自动化测试的完整实战方案。一、Cloud Tasks 与示例程序概览Cloud Tasks 是 Google Cloud 提供的分布式任务队列服务用于在应用之间异步执行任务它将任务投递到队列按调度策略可靠地推送给指定的 HTTP 端点即任务处理器。示例目录 cloud_tasks/snippets 演示了使用官方 Python 客户端库google-cloud-tasks的最核心用法包含两个命令行示例程序create_http_task.py简单的命令行程序创建一个任务并推送到指定 URL 端点create_http_task_with_token.py简单的命令行程序创建一个携带授权头OIDC 令牌的任务并推送到指定 URL 端点。两者的核心区别在于前者直接将请求体发送到公开端点后者额外附加了服务账号生成的 OIDC 令牌用于在受保护的端点如 Cloud Run、Cloud Functions上完成身份验证。除两个任务创建程序外目录中还提供了队列生命周期管理脚本create_queue.py、delete_queue.py、list_queues.py、对应测试文件以及依赖清单形成一个完整的可运行示例集合。二、本地运行前置条件2.1 环境与身份认证在本地运行示例前需要准备一个可用的 Google Cloud 项目并在项目中启用 Cloud Tasks API按照官方指南搭建 Python 开发环境安装 Python 3.10 及以上版本、配置pip完成应用默认凭证ADCApplication Default Credentials认证例如执行gcloud auth application-default login或为服务账号配置环境变量GOOGLE_APPLICATION_CREDENTIALS。认证完成后客户端库会在运行时自动读取凭证无需在代码中显式传递密钥。2.2 安装依赖进入示例目录后安装项目依赖pip install -r requirements.txtrequirements.txt 中锁定了客户端库版本google-cloud-tasks2.18.0示例还依赖google.protobuf中的duration_pb2与timestamp_pb2随客户端库自动安装用于表示调度时间和执行截止时间等 Protobuf 时间类型。若需运行测试另需安装 requirements-test.txt 中的pytest。2.3 测试运行配置可选示例目录内的 noxfile_config.py 说明了 CI 测试的运行约束默认忽略 Python 3.8/3.9/3.11/3.12/3.13 版本即主要在 3.10 上测试、强制开启类型注解检查enforce_type_hints: True并通过环境变量GOOGLE_CLOUD_PROJECT指定测试项目。这从侧面说明示例代码需要在新 Python 版本与带类型注解的写法下保持可运行。三、创建队列任务必须归属于某个队列因此第一步是创建队列。README 推荐使用 Cloud SDK 的 gcloud 命令创建名为my-queue的队列gcloud tasks queues create my-queue队列创建成功后可通过以下命令查看已创建的队列及其位置gcloud tasks queues list gcloud tasks queues describe my-queuedescribe输出中的name字段格式为projects/my-project/locations/us-central1/queues/my-queue其中us-central1即队列的 location ID后续设置环境变量时需要用到。除 gcloud 外也可直接用 Python API 创建队列。create_queue.py 展示了等价实现from google.cloud import tasks_v2 def create_queue(project: str, location: str, queue_id: str) - tasks_v2.Queue: # Create a client. client tasks_v2.CloudTasksClient() # Use the client to send a CreateQueueRequest. return client.create_queue( tasks_v2.CreateQueueRequest( parentclient.common_location_path(project, location), queuetasks_v2.Queue(nameclient.queue_path(project, location, queue_id)), ) )关键点common_location_path生成projects/{project}/locations/{location}父路径queue_path生成完整队列路径projects/{project}/locations/{location}/queues/{queue_id}。同理delete_queue.py 和 list_queues.py 分别实现了队列的删除与列举list_queues返回队列完整路径名称列表。四、命令行运行示例4.1 设置环境变量按 README 的步骤依次导出以下环境变量项目 IDexport PROJECT_IDmy-project-id队列 ID创建队列时指定已有队列可通过gcloud tasks queues list查看export QUEUE_IDmy-queueLocation ID通过gcloud tasks queues describe my-queue的name字段获取如us-central1export LOCATION_IDus-central14.2 创建 HTTP 目标任务设置任务处理端点的环境变量示例 URL 仅为示意export URLhttps://example.com/task_handler运行示例程序创建任务并将其推送到指定端点同时附带 payloadpython create_http_task.py --project$PROJECT_ID --queue$QUEUE_ID --location$LOCATION_ID --url$URL --payloadhello程序支持的完整命令行参数如下对应 create_http_task.py 中的argparse定义参数必填说明--project是队列所在项目 ID--queue是队列 ID短名称--location是队列所在位置如us-central1--url是任务请求发送到的完整 URL 路径--payload否附加到推送任务的可选负载--in_seconds否从现在起多少秒后调度任务整数--task_name否新创建任务的名称运行成功后任务会被加入队列并由 Cloud Tasks 服务按队列配置异步投递到--url指定的端点请求体内容为--payload传入的字符串。五、create_http_task.py 源码级解析5.1 函数签名与核心参数create_http_task.py 的核心函数create_http_task签名如下def create_http_task( project: str, location: str, queue: str, url: str, json_payload: Dict, scheduled_seconds_from_now: Optional[int] None, task_id: Optional[str] None, deadline_in_seconds: Optional[int] None, ) - tasks_v2.Task:各参数含义project/location/queue定位队列的三元组最终拼成队列路径projects/{project}/locations/{location}/queues/{queue}url任务投递的目标 URLjson_payload以 JSON 形式发送的请求体注意命令行传入的--payload在脚本中直接作为该参数传入因此 CLI 用法里它是一个普通字符串scheduled_seconds_from_now距当前时间的调度延迟秒对应任务的schedule_timetask_id新任务的显式 ID不传时由服务端自动生成deadline_in_seconds任务的执行截止时间秒对应dispatch_deadline。5.2 任务对象构造细节client tasks_v2.CloudTasksClient() task tasks_v2.Task( http_requesttasks_v2.HttpRequest( http_methodtasks_v2.HttpMethod.POST, urlurl, headers{Content-type: application/json}, bodyjson.dumps(json_payload).encode(), ), name( client.task_path(project, location, queue, task_id) if task_id is not None else None ), )从源码可以看出三个实现要点HTTP 方法固定为 POST请求头显式声明Content-type: application/json请求体为json_payload序列化后的 UTF-8 字节任务名称只有显式传入task_id时才通过client.task_path(...)构造完整路径projects/{project}/locations/{location}/queues/{queue}/tasks/{task_id}否则置为None由服务端生成幂等 ID协议类型HttpRequest、Task均来自google.cloud.tasks_v2属于 gRPC/Protobuf 消息类型。5.3 调度时间与执行截止时间# Convert seconds from now to an absolute Protobuf Timestamp if scheduled_seconds_from_now is not None: timestamp timestamp_pb2.Timestamp() timestamp.FromDatetime( datetime.datetime.utcnow() datetime.timedelta(secondsscheduled_seconds_from_now) ) task.schedule_time timestamp # Convert deadline in seconds to a Protobuf Duration if deadline_in_seconds is not None: duration duration_pb2.Duration() duration.FromSeconds(deadline_in_seconds) task.dispatch_deadline duration这两段代码分别回答了何时执行与执行超时上限两个问题schedule_time由当前 UTC 时间加上scheduled_seconds_from_now得到绝对时间戳未设置时任务立即进入投递调度dispatch_deadline指定任务从首次尝试到最终放弃前的最大执行时长原型示例测试中使用了 900 秒超过后任务会被标记为失败并进入重试流程重试策略由队列配置决定。5.4 发送创建请求return client.create_task( tasks_v2.CreateTaskRequest( # The queue to add the task to parentclient.queue_path(project, location, queue), # The task itself tasktask, ) )CreateTaskRequest由父队列路径parent与任务对象task组成调用后返回服务端确认的tasks_v2.Task实例。六、create_http_task_with_token.pyOIDC 认证任务对于部署在受保护服务如 Cloud Run、Cloud Functions 需要run.invoker调用权限上的任务端点需要携带 OpenID ConnectOIDC令牌验证调用方身份。create_http_task_with_token.py 展示了这一场景def create_http_task_with_token( project: str, location: str, queue: str, url: str, payload: bytes, service_account_email: str, audience: Optional[str] None, ) - tasks_v2.Task: client tasks_v2.CloudTasksClient() task tasks_v2.Task( http_requesttasks_v2.HttpRequest( http_methodtasks_v2.HttpMethod.POST, urlurl, oidc_tokentasks_v2.OidcToken( service_account_emailservice_account_email, audienceaudience, ), bodypayload, ), ) return client.create_task( tasks_v2.CreateTaskRequest( parentclient.queue_path(project, location, queue), tasktask, ) )与无认证版本相比核心差异集中在oidc_token字段service_account_email指定用于生成 OIDC 令牌的服务账号邮箱Cloud Tasks 会代该账号签发令牌附加到请求的Authorization头audience可选令牌的受众标识通常设置为目标服务 URL。对于 Cloud Run/Cloud Functions若不显式指定服务端默认使用完整的 URL 作为 audience。使用该方案时还需为目标服务账号授予调用目标服务的 IAM 角色例如 Cloud Run 的roles/run.invoker并确保任务队列所在项目能访问该服务账号。测试文件中使用的示例服务账号为test-run-invokerpython-docs-samples-tests.iam.gserviceaccount.com见 create_http_task_with_token_test.py可作为配置参考格式。七、测试验证示例的自动化保障目录中的测试文件展示了如何在真实 GCP 项目上验证任务创建逻辑create_http_task_test.py通过 pytest fixture 动态创建临时队列队列 ID 使用uuid.uuid4().hex保证唯一测试结束后在 teardown 中删除队列测试用例调用create_http_task并断言返回任务的name以队列路径开头、http_request.url与传入 URL 一致。其中scheduled_seconds_from_now180、deadline_in_seconds900的取值验证了调度与截止时间的组合用法并借助google.api_core.retry.Retry装饰器提升测试在弱网下的稳定性create_http_task_with_token_test.py除上述断言外还额外断言task.http_request.oidc_token.service_account_email与传入的服务账号一致验证 OIDC 令牌配置被正确写入任务对象。由于测试需要真实 Cloud Tasks API 凭证通过GOOGLE_CLOUD_PROJECT环境变量指定项目它们通常由 CI基于 nox 与 noxfile_config.py 的配置在受控测试项目中执行本地可参考 requirements-test.txt 安装pytest后运行pytest命令。八、完整流程总结一个完整的 Cloud Tasks HTTP 任务从创建到投递的链路如下启用 API 并完成认证ADC / gcloud 登录创建队列gcloud tasks queues create my-queue或调用 create_queue.py 中的 Python API准备任务处理器部署 HTTP 端点若端点受保护则准备服务账号及 audience运行示例设置PROJECT_ID、QUEUE_ID、LOCATION_ID、URL环境变量执行python create_http_task.py --project... --queue... --location... --url... --payloadhello或使用create_http_task_with_token.py的 OIDC 方案验证与运维通过gcloud tasks queues describe/list观察队列通过任务端点的访问日志确认投递结果使用 delete_queue.py 清理不再使用的队列。九、可继续深入阅读的仓库资源cloud_tasks/snippets/README.md官方 README 原文本文的骨架来源cloud_tasks/snippets/create_http_task.py无认证 HTTP 任务创建源码cloud_tasks/snippets/create_http_task_with_token.pyOIDC 认证任务创建源码cloud_tasks/snippets/create_queue.py、delete_queue.py、list_queues.py队列生命周期管理cloud_tasks/snippets/create_http_task_test.py 与 create_http_task_with_token_test.py集成测试参考cloud_tasks/snippets/requirements.txt客户端库版本锁定google-cloud-tasks2.18.0。赞分享示例工程【免费下载链接】python-docs-samplesCode samples used on cloud.google.com项目地址https://gitcode.com/GitHub_Trending/py/python-docs-samples点击查看免费下载相关推荐python-docs-samples 实战用 Google Cloud Tasks 与 App Engine 构建可重试的异步任务推送体系python docs samples 实战用 Google Cloud Tasks 与 App Engine 构建可重试的异步任务推送体系 本篇技术指南基于示例工程gogcli 实战指南使用 gog tasks add 在终端创建与管理 Google Tasks 任务gogcli 实战指南使用 gog tasks add 在终端创建与管理 Google Tasks 任务 gog tasks add 是 gogcli htt使用 gws CLI 创建 Google Tasks 任务列表并批量添加任务完整实操指南使用 gws CLI 创建 Google Tasks 任务列表并批量添加任务完整实操指南 本指南围绕 Google Workspace CLI gws 的上一篇3步完成AI 3D生成Hunyuan3D-2本地部署完整指南下一篇如何支持13种语言的实时转写Voxtral-Mini-4B-Realtime-2602-NPU 多语言能力探秘创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表