Taskcluster API 客户端

此库是 Rust 中 Taskcluster 的完整接口。它为所有 Taskcluster API 方法提供异步接口，以及一些实用函数。

用法

有关详细使用信息，请参阅 docs.rs。

兼容性

此库与 Taskcluster 本身进行版本控制。也就是说，版本 x.y.z 的客户端包含对应 Taskcluster 版本 x.y.z 的 API 方法。Taskcluster 仔细维护 API 兼容性，并在主要版本内保证兼容性。这意味着任何版本为 x.* 的客户端都将针对任何版本为 x.* 的 Taskcluster 服务工作，并且很可能适用于许多其他主要版本的 Taskcluster 服务。任何不兼容性都会在 变更日志 中说明。

lib.rs:

Rust Taskcluster 客户端

有关使用 Taskcluster 客户端的通用指南，请参阅 调用 Taskcluster API。

此客户端是围绕 reqwest 的便利包装器，为每个 API 端点提供命名函数，并添加了诸如身份验证和重试等功能。

用法

设置

在调用 API 端点之前，您需要使用 ClientBuilder 类型构建一个客户端。这允许根据构建器模式仅使用所需的功能构建客户端。您至少需要提供根 URL 来标识 API 调用应指向的 Taskcluster 部署。

每种服务都有一个类型，例如，Queue 和 Auth。每种服务类型都定义了特定于该服务API端点的函数。每个类型都有一个关联的 new 函数，该函数接收一个 Into<ClientBuilder>。作为一个快捷方式，你可以向 new 传递一个字符串，该字符串将被视为根URL。

以下是一个未认证客户端的简单设置和使用示例

use taskcluster::Auth;
let auth = Auth::new(root_url)?;
let resp = auth.client("static/taskcluster/root").await?;
assert_eq!(resp, json!({"clientId": "static/taskcluster/root"}));
Ok(())

以下是一个提供凭证的示例，在这种情况下，通过 标准环境变量 提供凭证。

use std::env;
use taskcluster::{ClientBuilder, Queue, Credentials};
let creds = Credentials::from_env()?;
let root_url = env::var("TASKCLUSTER_ROOT_URL").unwrap();
let client = Queue::new(ClientBuilder::new(&root_url).credentials(creds))?;
let res = client.cancelTask("G08bnnBuR6yDhDLJkJ6KiA").await?;
println!("{}", res.get("status").unwrap());
Ok(())

授权作用域

如果你希望代表具有比你自己更小作用域的第三方执行请求，你可以指定 你的请求应允许使用的作用域。

这些“授权作用域”在客户端进行配置

use std::env;
use serde_json::json;
use taskcluster::{ClientBuilder, Queue, Credentials};
let creds = Credentials::from_env()?;
let root_url = env::var("TASKCLUSTER_ROOT_URL").unwrap();
let client = Queue::new(
ClientBuilder::new(&root_url)
.credentials(creds)
.authorized_scopes(vec!["just:one-scope"]))?;
let res = client.createTask("G08bnnBuR6yDhDLJkJ6KiA", &task).await?;
Ok(())

调用API方法

API方法作为对应客户端对象的方法可用。它们使用大写蛇形命名（例如，createTask），以匹配Taskcluster文档。

每个方法按以下顺序接收参数，适用于该方法

• 位置参数（字符串被插入到URL中）
• 请求体（有效载荷）
• URL查询参数

有效载荷以 serde_json::Value 的形式提供，其内容应与API方法的输入模式匹配。URL查询参数都是可选的。

例如，以下列出所有Auth客户端

use taskcluster::{Auth, ClientBuilder, Credentials};
let auth = Auth::new(ClientBuilder::new(&root_url))?;
let mut continuation_token: Option<String> = None;
let limit = Some("10");

loop {
let res = auth
.listClients(None, continuation_token.as_deref(), limit)
.await?;
for client in res.get("clients").unwrap().as_array().unwrap() {
println!("{:?}", client);
}
if let Some(v) = res.get("continuationToken") {
continuation_token = Some(v.as_str().unwrap().to_owned());
} else {
break;
}
}

错误处理

所有5xx（服务器错误）响应都会自动重试。所有4xx（客户端错误）响应都会转换为 Result::Err。所有其他响应都被视为成功响应。请注意，这包括3xx（重定向）响应；客户端不会自动遵循此类重定向。

客户端方法返回 anyhow::Error，但在需要时可以将其转换为 reqwest::Error。作为一个获取错误HTTP状态码的常见情况，使用 err_status_code。此方法返回的 reqwest::StatusCode 类型是从此crate重新导出的。

低级访问

除了使用特定于服务的类型外，还可以通过路径直接使用 Client 类型调用API方法

use std::env;
use taskcluster::{ClientBuilder, Credentials};
let creds = Credentials::from_env()?;
let root_url = env::var("TASKCLUSTER_ROOT_URL").unwrap();
let client = ClientBuilder::new(&root_url).credentials(creds).build()?;
let resp = client.request("POST", "api/queue/v1/task/G08bnnBuR6yDhDLJkJ6KiA/cancel", None, None).await?;
assert!(resp.status().is_success());

上传和下载对象

包含针对从/到Taskcluster对象服务进行弹性上传/下载的专用支持的 taskcluster-upload 和 taskcluster-download crate。这些功能将同时与对象服务API接口并进行协商上传/下载方法。在所有情况下，你必须提供一个预配置的 Object 客户端以及对象服务API方法所需的参数。

生成URL

要为API方法生成一个未签名的URL，请使用 <method>_url

use taskcluster::{Auth, ClientBuilder};
let root_url = env::var("TASKCLUSTER_ROOT_URL").unwrap();
let auth = Auth::new(ClientBuilder::new(&root_url))?;
let url = auth.listClients_url(Some("static/"), None, None)?;
assert_eq!(url, "https://tc-tests.example.com/api/auth/v1/clients/?prefix=static%2F".to_owned());

生成临时凭证

create_named_temp_creds 方法创建临时凭证

use std::env;
use std::time::Duration;
use taskcluster::Credentials;
let creds = Credentials::from_env()?;
let temp_creds = creds.create_named_temp_creds(
"new-client-id",
Duration::from_secs(3600),
vec!["scope1", "scope2"])?;
assert_eq!(temp_creds.client_id, "new-client-id");

此外还有一个create_temp_creds方法可以创建无名称的临时凭证，但不建议使用。

生成时间戳

Taskcluster API期望ISO 8601时间戳，类似于JavaScript中的Date.toJSON方法生成的。如果包含了serde功能，chronocrate支持生成兼容的时间戳。此crate通过启用该功能重新导出chrono。为了重复其他Taskcluster客户端库中的fromNow函数的功能，可以使用类似下面的代码：

use taskcluster::chrono::{DateTime, Utc, Duration};
use serde_json::json;

let expires = Utc::now() + Duration::days(2);
let json = json!({ "expires": expires });

生成SlugIDs

使用slugidcrate创建slugIds（例如用于taskId）。