# General Translation Platform: 获取孤立文件
URL: https://generaltranslation.com/zh/docs/platform/openapi/reference/files/orphaned-files.mdx
---

title: 获取孤立文件
description: 查找不再与当前源文件关联的 General Translation 文件。获取孤立文件的 API 参考。

method: POST
---

返回某个 分支 上文件 ID 不在你提供的当前文件 ID 列表中的文件。用于检测在本地已移动、重命名或删除的文件。

## 概览 [#overview]

```http
POST https://api2.gtx.dev/v2/project/files/orphaned
```

**权限** `project:files:read` · **速率限制** 中 (120/分钟) 

在同步分支之前检测过期文件。之后如需移动或重命名这些文件，请使用[移动文件](/docs/platform/openapi/reference/files/move-files)。

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

* 系统会将该 分支 的头文件与你发送的 `fileIds` 进行比对。
* 分支 上凡是 `fileId` 不在该列表中的文件，都会作为孤立文件返回。
* `branchId` 必须属于该项目，否则请求会返回 `404`。
* 如果 `fileIds` 列表为空，分支 上的所有文件都会被标记为孤立文件。

## 请求 [#request]

### 请求头

| 请求头               | 说明               | 必填 |
| ----------------- | ---------------- | -- |
| `x-gt-api-key`    | 项目或组织 API 密钥。    | 是  |
| `x-gt-project-id` | 项目 ID。使用组织密钥时必填。 | 否  |

### 请求体

**内容类型** `application/json`

| 字段         | 描述                               | 类型         | 可选 | 默认值  |
| ---------- | -------------------------------- | ---------- | -- | ---- |
| `branchId` | 要检查的分支；必填。                       | `string`   | 否  | —    |
| `fileIds`  | 要保留的当前文件 ID。未包含在此列表中的文件将被视为孤立文件。 | `string[]` | 是  | `[]` |

## 响应 [#response]

**状态** `200 OK`

```json title="Response"
{
  "orphanedFiles": [
    {
      "fileId": "file_...",
      "versionId": "ver_...",
      "fileName": "en/removed.json"
    }
  ]
}
```

## 错误 [#errors]

| 状态    | 原因                                 |
| ----- | ---------------------------------- |
| `400` | 请求体无效，或缺少 `branchId`。              |
| `401` | 缺少 API 密钥，或 API 密钥无效。              |
| `403` | API 密钥不具备 `project:files:read` 权限。 |
| `404` | 未找到分支。                             |
| `429` | 已超出速率限制。                           |

## 示例 [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/files/orphaned \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "br_...",
    "fileIds": ["file_a...", "file_b..."]
  }'
```