# General Translation Platform: awaitJobs
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/translation/await-jobs.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 轮询排队中的翻译任务，直到其完成、失败或超时。awaitJobs 的 API 参考。

等待所有任务都变为 `completed`、`failed` 或 `unknown` 状态，或直至达到超时时间。支持翻译任务和初始化作业。

## 概览 [#overview]

将 [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) 的结果或任务 ID 数组传给 `awaitJobs`，也可以选择传入轮询设置。它最终会返回每个 任务 的状态。

```typescript
const gt = new GT({ projectId: 'your-project-id', apiKey: 'your-api-key' });

const enqueueResult = await gt.enqueueFiles(uploadedFiles, {
  sourceLocale: 'en',
  targetLocales: ['es', 'fr'],
});

const result = await gt.awaitJobs(enqueueResult);

if (result.complete) {
  console.log('所有任务已完成');
} else {
  console.log('已超时 — 部分任务仍在进行中');
}
```

签名：

```typescript
awaitJobs(
  jobs: EnqueueFilesResult | string[],
  options?: AwaitJobsOptions
): Promise<AwaitJobsResult>
```

*警告：`complete: true` 表示所有 任务 都已进入终止状态——这**并不**意味着所有 任务 都已成功。请检查每个 `job.status`，确认是否成功。*

## 工作方式 [#how-it-works]

* **自动轮询。** 代替手动轮询循环——你无需自己在 `while` 循环中调用 [`checkJobStatus`](/docs/platform/core/reference/gt-class-methods/translation/check-job-status)。
* **终止状态。** 当所有任务都处于 `completed`、`failed` 或 `unknown` 状态时，该方法才会返回。API 找不到的任务会被视为 `'unknown'`。
* **截止时间。** 每个状态请求的超时上限为 60 秒，若整体剩余时间不足 60 秒，则以剩余时间为准。超时后，方法会返回最后已知的状态，并附带 `complete: false`；此时任务可能仍处于排队中、处理中或未知状态。自定义 fetch 实现必须支持取消操作，才能及时停止。
* **错误。** 截止时间之前发生的状态错误会导致 Promise 被拒绝；截止时间之后发生的错误则会改为返回不完整的结果。停止轮询不会取消远程任务。
* **空输入。** 校验完凭据和项目 ID 后，若输入为空，该方法会返回 `{ complete: true, jobs: [] }`。

## 参数 [#parameters]

| 参数                    | 描述                                                                                                           | 类型                                                                                               | 可选         | 默认值 |   |
| --------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ---------- | --- | - |
| [`jobs`](#jobs)       | [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) 返回的结果或任务 ID 数组。 | [`EnqueueFilesResult`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) | `string[]` | 否   | — |
| [`options`](#options) | 轮询配置。                                                                                                        | `AwaitJobsOptions`                                                                               | 是          | —   |   |

### `jobs`

**类型** [`EnqueueFilesResult`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) | `string[]` · **必填**

由 [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) 返回的结果，或由其他工作流 (如 [`setupProject`](/docs/platform/core/reference/gt-class-methods/translation/setup-project)) 返回的任务 ID。传入入队结果时，其 `jobData` 用于标识需要轮询的 任务。

### `options`

**类型** `AwaitJobsOptions` · **可选**

来自 `generaltranslation/types` 的轮询配置。与 [API 轮询选项](/docs/platform/core/reference/api-client#job-polling) 不同，类选项不提供 `onPoll`，也不接受调用方传入的信号：

| 字段                       | 描述                 | 类型       | 可选 | 默认值           |
| ------------------------ | ------------------ | -------- | -- | ------------- |
| `pollingIntervalSeconds` | 轮询 `status` 更新的频率。 | `number` | 是  | `5`           |
| `timeoutSeconds`         | 返回当前状态结果前的最长等待时间。  | `number` | 是  | `600` (10 分钟) |

## 返回值 [#returns]

**类型** `Promise<AwaitJobsResult>`

解析结果为一个 `AwaitJobsResult`，其中包含一个总体标志以及每个 任务 的最终状态：

```typescript
type AwaitJobsResult = {
  /** 所有 任务 是否已达到终止状态（不一定是成功）。 */
  complete: boolean;
  jobs: JobResult[];
};

type JobResult = {
  jobId: string;
  status: JobStatus;
  error?: { message: string };
};
```

| 属性              | 描述                                            | 类型                                                                                                   |
| --------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `complete`      | 如果没有任何任务仍在进行中，则为 `true`；如果已达到超时时间，则为 `false`。 | `boolean`                                                                                            |
| `jobs`          | 每个任务的最终状态。                                    | `JobResult[]`                                                                                        |
| `jobs[].jobId`  | 任务标识符。                                        | `string`                                                                                             |
| `jobs[].status` | 最新状态；达到超时时间时可能仍为 `'queued'` 或 `'processing'`。 | [`JobStatus`](/docs/platform/core/reference/gt-class-methods/translation/check-job-status#jobstatus) |
| `jobs[].error`  | 任务失败时的错误详情。                                   | `{ message: string }`                                                                                |

## 示例 [#examples]

直接轮询任务 ID：

```typescript
const result = await gt.awaitJobs(['job-123', 'job-456']);
```

轮询 [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) 的结果：

```typescript title="index.ts"
import { GT } from 'generaltranslation';

const gt = new GT({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
});

// 上传并加入队列
const { uploadedFiles } = await gt.uploadSourceFiles(files, {
  sourceLocale: 'en',
});

const enqueueResult = await gt.enqueueFiles(uploadedFiles, {
  sourceLocale: 'en',
  targetLocales: ['es', 'fr', 'de'],
});

// 等待所有任务完成（每 10 秒轮询一次，5 分钟后超时）
const result = await gt.awaitJobs(enqueueResult, {
  pollingIntervalSeconds: 10,
  timeoutSeconds: 300,
});

if (!result.complete) {
  console.warn('Some jobs did not finish in time');
}

// 检查各任务结果
for (const job of result.jobs) {
  if (job.status === 'completed') {
    console.log(`Job ${job.jobId} succeeded`);
  } else if (job.status === 'failed') {
    console.error(`Job ${job.jobId} failed: ${job.error?.message}`);
  }
}
```

## 备注 [#notes]

* API 未找到的 任务 会被视为 `'unknown'` 状态。
* 输入为空时，会在身份验证通过后返回 `{ complete: true, jobs: [] }`。
* 超时时返回最后一次接受的状态，这些状态未必是终态；之后才到达的轮询结果会被丢弃。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.