> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockx.chaintable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 服务 API

> 通过 gRPC 提交、订阅、查询任务和同步调用函数。

gRPC 服务定义 BlockX 对外的执行契约。选择对应部署的服务；请求中的配置字节包含选定 Call Builder 或 Writer Plugin 的 JSON。

## Worker 任务操作

在 BlockX 仓库中，`api/grpc/worker/worker.proto` 定义 Worker 服务，`api/grpc/bundleworker/bundle_worker.proto` 定义 bundle 服务身份。

| RPC | 请求 | 响应 |
| - | - | - |
| `RequestTaskSlot` | `task_id`、`ttl_ms` | `slot_id`、`state`、`alloc_seq` |
| `SubmitTask` | `task`、可选 `slot_id` | 当前 `state` |
| `GetTaskResult` | `task_id` | 标识、状态及可用的终态结果 |
| `WatchTasks` | `task_ids` | 当前快照与终态更新流 |

执行期间保持 Watch 连接。其生命周期参与任务执行；见[执行语义](/zh/concepts/execution-semantics)。

## TaskInput

| 字段 | 类型 | 含义 |
| - | - | - |
| `task_id` | `string` | 调用方提供的任务标识 |
| `function_call_config` | `{type, config}` | 已注册 Call Builder 名称与 JSON 字节 |
| `result_handler` | `{type, config}` | 可选 Writer Plugin 名称与 JSON 字节 |
| `task_timeout_ms` | `int64` | 以毫秒计的执行时长；零使用 Worker 默认值；负值或超限值被拒绝 |

Go JSON 表示使用 `functionCallConfig`、`resultHandler` 和 `taskTimeoutMs`，与 protobuf 字段名不同。Plugin 配置保留自己的 JSON 键；见[任务配置](/zh/reference/task-configuration)。

## Coordinator 选址

`CoordinatorService.ReserveWorkerSlot` 与 `BundleCoordinatorService.ReserveWorkerSlot` 在对应部署预占容量。提供 `task_id`，再使用返回的 `worker_addr` 和 `slot_id` 提交。Coordinator 选择资源，Worker 执行任务并报告结果。

协议来源：`api/grpc/coordinator/coordinator.proto` 和 `api/grpc/bundlecoordinator/bundle_coordinator.proto`。

## 同步调用

定义位于 `api/grpc/syncinvoker/sync_invoker.proto`。

| RPC | 输入 | 输出 |
| - | - | - |
| `Invoke` | 一个函数来源、`args_json`、可选 `deadline_unix_ms` | `call_id`、`success`、`result_json` 或 `failure`、执行与排队时长 |
| `DebugInvoke` | 相同输入形状 | 调用结果及 `debug_output` |
| `Precheck` | `source_code` | 审计结论与检查结果，不执行函数 |

`function_id` 与 `inline_source` 必须恰好选择一个。`args_json` 包含 JSON 数组。`deadline_unix_ms` 是绝对截止时间，与任务的时长字段不同。

## 相关文档

* [同步调用与调试](/zh/guides/synchronous-invocation)
* [结果与错误](/zh/reference/results-and-errors)
* [内部协议](/zh/architecture/protocols)
* [用 Go 提交任务](/zh/development/submit-task-example)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.