# 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`) 或达到超时时间时 resolve。它是 [`checkJobStatus`](/docs/platform/core/reference/gt-class-methods/translation/check-job-status) 的便捷封装，会自动为你处理轮询。

## 概览 [#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'`。
* **尽力而为的超时。** 超时只是一个尽力而为的限制——该方法会先完成当前这一轮轮询，再返回结果。
* **空输入。** 如果入队结果不包含任何任务，或者任务 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` · **可选**

轮询配置：

| 字段                       | 描述                 | 类型       | 可选 | 默认值           |
| ------------------------ | ------------------ | -------- | -- | ------------- |
| `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` | 最终状态：`'completed'`、`'failed'` 或 `'unknown'`。  | [`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'` 状态。
* 空的入队结果或任务 ID 数组会立即返回 `{ complete: true, jobs: [] }`。
* 超时时间是一个尽力而为的限制——该方法会在返回前先完成当前轮询。

## Sitemap

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