# 适用于依赖项提交的 REST API 终结点

使用 REST API 提交依赖项。

## 关于依赖项提交

可以使用 REST API 提交项目的依赖项。 这使你可以将依赖项（如编译或生成软件时解析的依赖项）添加到 GitHub依赖项关系图功能，从而更全面地了解项目的所有依赖项。

依赖项关系图显示你使用 API 提交的任何依赖项，以及从存储库中的清单或锁定文件（例如 `package-lock.json` JavaScript 项目中的文件）标识的任何依赖项。 有关查看依赖项关系图的详细信息，请参阅 [探索仓库的依赖项](/zh/enterprise-server@3.22/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/explore-dependencies#viewing-the-dependency-graph)。

提交的依赖项如存在任何已知漏洞，将收到 Dependabot alerts 和 Dependabot security updates。 你只会对来自 Dependabot alerts 所支持生态系统之一的依赖项获得 GitHub Advisory Database。 有关这些生态系统的详细信息，请参阅 [GitHub 通告数据库](/zh/enterprise-server@3.22/code-security/concepts/vulnerability-reporting-and-management/github-advisory-database#github-reviewed-vulnerability-advisories)。 对于通过  依赖项提交 API提交的可传递依赖项，如果更新可用， Dependabot 将自动打开拉取请求以更新父依赖项。

提交的依赖项在组织的依赖项见解中\_不\_可用。

可以通过快照的形式提交依赖项。 快照是一组与提交的唯一识别码 (SHA) 和其他元数据相关联的依赖项，反映了你的存储库在某次提交时的当前状态。 可以选择使用预先创建的操作，或创建自己的操作，在每次生成项目时，以所需的格式提交依赖项。 有关详细信息，请参阅“[使用依赖项提交 API](/zh/enterprise-server@3.22/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/use-dependency-submission-api)”。

可以提交多个依赖项集，以包含在依赖项关系图中。 REST API 使用 `job.correlator` 属性和快照的 `detector.name` 类别来确保显示每个工作流的最新提交。 属性 `correlator` 本身是用于保持独立提交不同的主要字段。 例如 `correlator` 可以是操作运行中两个可用变量的简单组合：`<GITHUB_WORKFLOW> <GITHUB_JOB>`。

存储库可以使用多个方法提交依赖项，这可能导致多次扫描同一包清单，这可能会导致每次扫描的输出不同。 依赖项关系图使用去重逻辑来分析输出，为每个清单文件优先选取最准确的信息。

依赖项关系图会依据以下优先级规则，仅显示每个清单文件的一个实例。

1. 用户提交具有最高优先级，因为它们通常是在项目构建期间创建的，包含最完整的信息。\*\*\*\*
   * 如果存在来自不同检测器的多个手动快照，这些快照将根据关联器按字母顺序进行排序，并且会采用第一个快照。
   * 如果有两个使用相同检测器的关联器，已解析的依赖项将合并。 有关关联器和检测器的详细信息，请参阅 [适用于依赖项提交的 REST API 终结点](/zh/enterprise-server@3.22/rest/dependency-graph/dependency-submission)。
2. **自动提交** 具有下一个优先级，因为它们也是在项目生成期间创建的，但不会由用户提交。
3. 静态分析结果会在没有其他可用数据的情况下被采用。\*\*\*\*

> \[!NOTE]
> Most endpoints use `Authorization: Bearer <YOUR-TOKEN>` and `Accept: application/vnd.github+json` headers, plus `X-GitHub-Api-Version: 2026-03-10`. Curl examples below omit these standard headers for brevity.

## Create a snapshot of dependencies for a repository

```
POST /repos/{owner}/{repo}/dependency-graph/snapshots
```

Create a new snapshot of a repository's dependencies.
The authenticated user must have access to the repository.
OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`owner`** (string) (required)
  The account owner of the repository. The name is not case sensitive.

* **`repo`** (string) (required)
  The name of the repository without the .git extension. The name is not case sensitive.

#### Body parameters

* **`version`** (integer) (required)
  The version of the repository snapshot submission.

* **`job`** (object) (required)
  * **`id`** (string) (required)
    The external ID of the job.
  * **`correlator`** (string) (required)
    Correlator provides a key that is used to group snapshots submitted over time. Only the "latest" submitted snapshot for a given combination of job.correlator and detector.name will be considered when calculating a repository's current dependencies. Correlator should be as unique as it takes to distinguish all detection runs for a given "wave" of CI workflow you run. If you're using GitHub Actions, a good default value for this could be the environment variables GITHUB\_WORKFLOW and GITHUB\_JOB concatenated together. If you're using a build matrix, then you'll also need to add additional key(s) to distinguish between each submission inside a matrix variation.
  * **`html_url`** (string)
    The url for the job.

* **`sha`** (string) (required)
  The commit SHA associated with this dependency snapshot. Maximum length: 40 characters.

* **`ref`** (string) (required)
  The repository branch that triggered this snapshot.

* **`detector`** (object) (required)
  A description of the detector used.
  * **`name`** (string) (required)
    The name of the detector used.
  * **`version`** (string) (required)
    The version of the detector used.
  * **`url`** (string) (required)
    The url of the detector used.

* **`metadata`** (object)
  User-defined metadata to store domain-specific information limited to 8 keys with scalar values.

* **`manifests`** (object)
  A collection of package manifests, which are a collection of related dependencies declared in a file or representing a logical group of dependencies.
  * **`key`** (object)
    A user-defined key to represent an item in manifests.
    * **`name`** (string) (required)
      The name of the manifest.
    * **`file`** (object)
      * **`source_location`** (string)
        The path of the manifest file relative to the root of the Git repository.
    * **`metadata`** (object)
      User-defined metadata to store domain-specific information limited to 8 keys with scalar values.
    * **`resolved`** (object)
      A collection of resolved package dependencies.
      * **`key`** (object)
        A user-defined key to represent an item in resolved.
        * **`package_url`** (string)
          Package-url (PURL) of dependency. See <https://github.com/package-url/purl-spec> for more details.
        * **`metadata`** (object)
          User-defined metadata to store domain-specific information limited to 8 keys with scalar values.
        * **`relationship`** (string)
          A notation of whether a dependency is requested directly by this manifest or is a dependency of another dependency.
          Can be one of: `direct`, `indirect`
        * **`scope`** (string)
          A notation of whether the dependency is required for the primary build artifact (runtime) or is only used for development. Future versions of this specification may allow for more granular scopes.
          Can be one of: `runtime`, `development`
        * **`dependencies`** (array of strings)
          Array of package-url (PURLs) of direct child dependencies.

* **`scanned`** (string) (required)
  The time at which the snapshot was scanned.

### HTTP response status codes

* **201** - Created

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X POST \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/dependency-graph/snapshots \
  -d '{
  "version": 0,
  "sha": "ce587453ced02b1526dfb4cb910479d431683101",
  "ref": "refs/heads/main",
  "job": {
    "correlator": "yourworkflowname_youractionname",
    "id": "yourrunid"
  },
  "detector": {
    "name": "octo-detector",
    "version": "0.0.1",
    "url": "https://github.com/octo-org/octo-repo"
  },
  "scanned": "2022-06-14T20:25:00Z",
  "manifests": {
    "package-lock.json": {
      "name": "package-lock.json",
      "file": {
        "source_location": "src/package-lock.json"
      },
      "resolved": {
        "@actions/core": {
          "package_url": "pkg:/npm/%40actions/core@1.1.9",
          "dependencies": [
            "@actions/http-client"
          ]
        },
        "@actions/http-client": {
          "package_url": "pkg:/npm/%40actions/http-client@1.0.7",
          "dependencies": [
            "tunnel"
          ]
        },
        "tunnel": {
          "package_url": "pkg:/npm/tunnel@0.0.6"
        }
      }
    }
  }
}'
```

**Response schema (Status: 201):**

* `id`: required, integer
* `created_at`: required, string
* `result`: required, string
* `message`: required, string