# 任务查询、分页与结果下载

本页按“找到任务 → 查看发送进度 → 查看计算状态 → 下载结果”的顺序介绍 Core 查询接口。Qiskit 用户可以用 service.scheduler，PennyLane 用户可以复用创建设备时传入的 scheduler。按已经保存的提交号或任务号选择对应示例。

## 准备查询客户端

先完成连接与认证。下面使用环境中的平台凭据创建客户端；已有 scheduler 时可以直接复用。

```python
import os
from quantum_source_sdk import SchedulerClient

scheduler = SchedulerClient(base_url=os.environ["QUANTUM_SOURCE_API_URL"])
organization_id = os.environ["QUANTUM_SOURCE_ORGANIZATION_ID"]
```

## 先分清自己保存的是哪个 ID

| 标识 | 来源 | 用在哪个查询 |
| --- | --- | --- |
| 提交 / 准备号 | prepared.preparation.id，或回执 submission_id | get_submission(submission_id)，从准备阶段开始跟踪发送进度。 |
| 任务号 | receipt.job_id 或 JobRead.id | get_job(job_id)，查询计算状态和结果。 |
| Qiskit 的任务集合 | job.platform_job_ids / job.submission_ids | 一个插件句柄可包含多条任务；从这两个列表读取各条任务或提交的 ID。 |

name 用于在列表中识别实验，查询时使用记录中的 ID。提交号对应发送过程，任务号对应设备上的计算任务。

## 1. 还没有任务号：查原提交

```python
submission_id = input("Existing submission ID: ").strip()
receipt = scheduler.get_submission(submission_id)
print(receipt.submission_status)
print(receipt.job_id)
```

get_submission 返回当前的 SubmissionReceipt。job_id 为 None 时，继续通过 submission_status 查看发送进度；取得 job_id 后即可查询计算状态。若提示发送结果待核实，保留原提交号，稍后再次查询。

| submission_status | 含义 |
| --- | --- |
| not_started | 准备记录尚未开始发送。 |
| queued | 平台已接受，正在等待发送。 |
| submitting | 平台发送处理中。 |
| submitted | 任务已关联到厂商受理记录，可继续查询计算状态。 |
| failed / cancelled | 这次平台提交流程失败或取消；与实际任务的 status 是不同层次。 |

需要找回提交号时，调用 list_submissions 查看当前身份可见的提交记录。每条记录包含 submission_id、发送状态，以及已取得的 job_id。

```python
submission_page = scheduler.list_submissions(limit=20)
for item in submission_page.submissions:
    print(item.submission_id, item.submission_status, item.job_id)
```

## 2. 已有任务号：查计算状态

```python
job_id = input("Existing job ID: ").strip()
job = scheduler.get_job(job_id)
print(job.id, job.status, job.shots)
```

get_job 查询一次当前状态，返回 JobRead。单条查询默认刷新厂商状态；需要持续查看进度时，使用下面的等待方法。

wait_for_job 会持续查询直到任务进入终态。timeout 设置本次等待时长，interval 设置查询间隔，verbose=True 显示简短的状态变化。

```python
job = scheduler.wait_for_job(
    job_id, timeout=300, interval=2, verbose=True,
)
print(job.status)
```

wait_for_job 在 Completed、Failed 或 Cancelled 等终态返回 JobRead，可通过 status 查看最终状态。wait_for_submission 同时等待平台发送和设备计算，成功时返回任务，失败或取消时抛出对应异常。省略 timeout 时使用客户端 wait_timeout_seconds（默认 1800 秒），省略 interval 时使用 poll_interval_seconds（默认 2 秒）。等待超时后可以继续查询同一个任务。

## 3. 查看组织的任务列表

```python
page = scheduler.list_jobs(
    organization_id=organization_id, limit=20,
)
for item in page.jobs:
    print(item.id, item.name, item.status)
```

list_jobs 返回 PaginatedJobs，page.jobs 包含当前用户在指定组织下的 JobList 条目。列表展示平台保存的状态；需要最新状态和 shots 等详情时，取 item.id 再调用 get_job。账号属于一个组织时可省略 organization_id，属于多个组织时填写目标组织 ID。

| 参数 | 含义 |
| --- | --- |
| organization_id | 账号可访问的组织 ID。 |
| limit=20 | 单页条数，允许 1–1000。 |
| cursor=None | None 表示第一页；之后原样传回服务端提供的 next_cursor。 |
| status=None | 由服务端筛选任务状态，例如 Completed。 |

```python
completed_page = scheduler.list_jobs(
    organization_id=organization_id, status="Completed", limit=20,
)
for item in completed_page.jobs:
    print(item.id, item.status)
```

## 4. 用 cursor 读取更多记录

cursor 表示下一次查询的分页位置。读取第一页时可省略；遍历全部记录时，将服务端返回的 next_cursor 原样传给下一次查询，直到读完全部页面。

```python
cursor = None
while True:
    page = scheduler.list_jobs(
        organization_id=organization_id, limit=100, cursor=cursor,
    )
    for item in page.jobs:
        print(item.id, item.status)
    cursor = page.pagination.next_cursor
    if not cursor:
        break
```

每个列表使用自身返回的 next_cursor。改变组织或筛选条件后，从第一页开始读取。Qiskit 的 service.backends 会自动读取设备目录的后续页面。

## 5. 成功之后读取统一结果

下面使用 get_job 返回的 JobRead 对象。状态为 Completed 时，可下载结果；代码使用不区分大小写的比较。

```python
if job.status.casefold() == "completed":
    result = scheduler.download_job_result(job)
    print(result.result_kind)
    print(result.primary_value)
else:
    print("No completed result yet:", job.status)
```

download_job_result 返回 UnifiedResult，通过 result_kind 和 primary_value 读取结果类型与数据。需要完整平台 JSON 响应时，使用 download_job_output(job)。

```python
if job.status.casefold() == "completed":
    payload = scheduler.download_job_output(job)
    print(payload.keys())
```

result_kind 为 counts 时，primary_value 是位串到测量次数的字典；为 probabilities 时，则是对应的概率数据。

## 查询设备能力与校准信息

设备当前的门集、拓扑和误差属性通过设备能力接口查询。任务级校准文件由 JobRead.calibration_data_url 指定；当前配套后端该字段为 None，因此本版本使用设备能力接口查看可用硬件信息。

## 超时或重启 Notebook 后怎么办

保存 submission_id 或 job_id。重新连接后，有提交号就调用 get_submission 或 wait_for_submission，有任务号就调用 get_job 或 wait_for_job，即可继续查看同一次实验的进度和结果。

## API 参考与下一步

列表分页、提交查询、任务等待和结果下载方法的完整参数与返回对象，统一在 Core API 参考中查阅。

- [Core 客户端 API](api.html#core)
- [接口实现与测试依据](api.html#evidence)

- [Core 单条、批次与恢复](core.html)
- [结果与常见问题](results.html)
- [设备发现与分页](backend-discovery.html)
- [底层提交协议](low-level.html)

## 下载本页 Jupyter Notebook

收录本页 Python 示例与说明，便于在 Jupyter Notebook 中学习和运行；安装命令保留为说明。

[下载《任务查询与分页》Notebook（.ipynb）](../../notebooks/sdk_user_guide_job_query.ipynb)