catalog-resource.md

title	目录资源，NuGet V3 API
description	目录是在 nuget.org 上创建和删除的所有包的索引。
author	joelverhagen
ms.author	jver
ms.date	10/30/2017
ms.topic	reference
ms.reviewer	kraigb
ms.openlocfilehash	ffbcb8dc18542f39c32a6d84b279c8eccaf98fc3
ms.sourcegitcommit	7e9c0630335ef9ec1e200e2ee9065f702e52a8ec
ms.translationtype	MT
ms.contentlocale	zh-CN
ms.lasthandoff	06/24/2020
ms.locfileid	85292303

目录

目录是记录包源上所有包操作（如创建和删除）的资源。 目录资源的 Catalog 服务索引中包含类型。 您可以使用此资源查询所有已发布的包。

Note

由于官方 NuGet 客户端不使用目录，因此并非所有包源都实现目录。

Note

目前，nuget.org 目录在中国不可用。 有关更多详细信息，请参阅NuGet/NuGetGallery # 4949。

版本控制

使用以下 @type 值：

@type 值	备注
Catalog/3.0。0	初始版本

基 URL

以下 Api 的入口点 URL 是 @id 与上述资源值关联的属性的值 @type 。 本主题使用占位符 URL {@id} 。

HTTP 方法

在目录资源中找到的所有 Url 仅支持 HTTP 方法 GET 和 HEAD 。

目录索引

目录索引是众所周知位置的文档，其中包含目录项列表，按时间顺序排列。 它是目录资源的入口点。

此索引由目录页组成。 每个目录页面都包含目录项。 每个目录项都表示一个事件，该事件涉及到某个时间点的单个包。 目录项可以表示从包源创建、未列出、重新列出或删除的包。 通过按时间顺序处理目录项，客户端可以生成在 V3 包源上存在的每个包的最新视图。

简而言之，目录 blob 具有以下层次结构：

• Index：目录的入口点。
• 页面：目录项的分组。
• 叶：表示目录项的文档，该目录项是单个包状态的快照。

每个目录对象都有一个名为的属性，该属性 commitTimeStamp 表示将项添加到目录的时间。 目录项将添加到名为 "提交" 的批次的目录页中。 同一提交中的所有目录项都具有相同的提交时间戳（ commitTimeStamp ）和提交 ID （ commitId ）。 放置在同一提交中的目录项表示在包源上的同一时间点附近发生的事件。 目录提交中没有排序。

由于每个包 ID 和版本都是唯一的，因此在一个提交中将永远不会有多个目录项。 这可确保单个包的目录项始终可以明确地按提交时间戳进行排序。

每个目录的提交永远不会超过一个 commitTimeStamp 。 换言之， commitId 是的冗余 commitTimeStamp 。

与按包 ID 编制索引的包元数据资源不同，目录仅通过时间进行索引（和查询）。

目录项始终按单调递增的时间顺序添加到目录中。 这意味着，如果在时间 X 添加目录提交，则不会使用小于或等于 X 的时间来添加目录提交。

以下请求将获取目录索引。

GET {@id}

目录索引是一个 JSON 文档，其中包含具有以下属性的对象：

名称	类型	必需	备注
commitId	字符串	是	与最新提交关联的唯一 ID
commitTimeStamp	字符串	是	最近提交的时间戳
count	integer	是	索引中的页数
items	对象数组	是	对象的数组，每个对象表示一个页

数组中的每个元素 items 都是一个对象，其中包含有关每个页面的一些最少的详细信息。 这些页面对象不包含目录叶（items）。 未定义此数组中元素的顺序。 客户端可以使用其属性在内存中对页面进行排序 commitTimeStamp 。

随着新页的引入， count 将递增，新的对象将出现在数组中 items 。

在将项添加到目录中时，索引的 commitId 将会更改，并且 commitTimeStamp 将增加。 这两个属性本质上是对 commitId 数组中所有页面和值的汇总 commitTimeStamp items 。

索引中的目录页对象

在目录索引的属性中找到的目录页对象 items 具有以下属性：

名称	类型	必需	备注
@id	字符串	是	要提取目录页的 URL
commitId	字符串	是	与此页中的最新提交关联的唯一 ID
commitTimeStamp	字符串	是	此页中的最新提交的时间戳
count	integer	是	目录页中的项数

与包元数据资源相比，在某些情况下，inlines 留在索引中，目录叶从不内联到索引中，必须始终使用页面的 URL 来提取 @id 。

示例请求

GET https://api.nuget.org/v3/catalog0/index.json

示例响应

[!code-JSON catalog-index.json]

目录页

"目录" 页是目录项的集合。 它是使用 @id 目录索引中找到的值之一提取的文档。 目录页的 URL 不应是可预测的，只应使用目录索引来发现。

新的目录项仅添加到具有最高提交时间戳或新页的目录索引页面。 将具有较高提交时间戳的页面添加到目录后，将永远不会将较旧的页面添加到或更改。

目录页文档是包含以下属性的 JSON 对象：

名称	类型	必需	备注
commitId	字符串	是	与此页中的最新提交关联的唯一 ID
commitTimeStamp	字符串	是	此页中的最新提交的时间戳
count	integer	是	页面中的项目数
items	对象数组	是	此页中的目录项
父级 (parent)	字符串	是	目录索引的 URL

数组中的每个元素 items 都是一个对象，其中包含有关目录项的一些最少的详细信息。 这些项对象不包含目录项的所有数据。 页的数组中项的顺序 items 未定义。 客户端可以使用其属性在内存中对项进行排序 commitTimeStamp 。

页中目录项的数目由服务器实现定义。 对于 nuget.org，每个页面中最多包含550个项目，但对于某些页面，实际数字可能较小，具体取决于下一个提交批处理的时间点大小。

引入新项 count 后，会递增，新目录项对象会出现在数组中 items 。

当向页面添加项时，所 commitId 做的更改和将 commitTimeStamp 增加。 这两个属性本质上是对 commitId 数组中所有和值的汇总 commitTimeStamp items 。

页面中的目录项对象

在目录页的属性中找到的目录项对象 items 具有以下属性：

名称	类型	必需	备注
@id	字符串	是	要提取目录项的 URL
@type	字符串	是	目录项的类型
commitId	字符串	是	与此目录项关联的提交 ID
commitTimeStamp	字符串	是	此目录项的提交时间戳
nuget： id	字符串	是	此叶相关的包 ID
nuget：版本	字符串	是	此叶相关的包版本

@type该值将是以下两个值之一：

1. nuget:PackageDetails：对应于 PackageDetails 目录叶文档中的类型。
2. nuget:PackageDelete：对应于 PackageDelete 目录叶文档中的类型。

有关每种类型含义的更多详细信息，请参阅下面的相应项类型。

示例请求

GET https://api.nuget.org/v3/catalog0/page2926.json

示例响应

[!code-JSON catalog-page.json]

目录叶

目录叶包含某些时间点特定包 ID 和版本的相关元数据。 它是使用 @id 目录页中的值提取的文档。 目录叶的 URL 不应是可预测的，应仅使用目录页来发现。

目录叶文档是包含以下属性的 JSON 对象：

名称	类型	必需	备注
@type	字符串或字符串数组	是	目录项的类型
目录： commitId	字符串	是	与此目录项关联的提交 ID
目录： commitTimeStamp	字符串	是	此目录项的提交时间戳
id	字符串	是	目录项的包 ID
published	字符串	是	包目录项的发布日期
版本	字符串	是	目录项的包版本

项类型

@type属性是字符串或字符串数组。 为方便起见，如果 @type 值为字符串，则应将其视为大小为1的任意数组。 并非的所有可能值 @type 都有记录。 但是，每个目录项都有以下两个字符串类型值中的一个：

1. PackageDetails：表示包元数据的快照
2. PackageDelete：表示已删除的包

包详细信息目录项

类型为的目录项 PackageDetails 包含特定包的包元数据（ID 和版本组合）的快照。 包源遇到以下任何情况时，将生成包详细信息目录项：

1. 推送包。
2. 已列出包。
3. 未列出包。
4. 包为重排。

包重排是一种管理手势，它实质上生成了现有包的虚设推送，无对包本身的任何更改。 在 nuget.org 上，在使用目录的后台作业之一中修复 bug 后，将使用重排。

使用目录项的客户端不应尝试确定哪些方案生成了目录项。 相反，客户端只需用目录项中包含的元数据更新任何已维护的视图或索引。 此外，应妥善处理重复或冗余的目录项目（幂等方式）。

包详细信息目录项除包含在所有目录叶上的属性外，还具有以下属性。

名称	类型	必需	备注
作者	字符串	否
created	字符串	否	首次创建包时的时间戳。 回退属性： published 。
dependencyGroups	对象数组	否	包的依赖项，按目标框架分组（与包元数据资源的格式相同）
弃用	对象 (object)	否	与包关联的弃用（与包元数据资源的格式相同）
description	字符串	否
iconUrl	字符串	否
isPrerelease	boolean	否	包版本是否为预发布版本。 可以从中检测到 version 。
语言	字符串	否
licenseUrl	字符串	否
列出	boolean	否	是否列出包
minClientVersion	字符串	否
packageHash	字符串	是	包哈希，使用标准基 64编码
packageHashAlgorithm	字符串	是
packageSize	integer	是	包的大小（以字节为单位） nupkg
packageTypes	对象数组	否	作者指定的包类型。
projectUrl	字符串	否
releaseNotes	字符串	否
requireLicenseAgreement	boolean	否	假设 false 排除
摘要	字符串	否
tags	字符串数组	否
title	字符串	否
verbatimVersion	字符串	否	最初在中找到的版本字符串。 nuspec

Package version 属性是规范化后的完整版本字符串。 这意味着，可以在此处包括 SemVer 2.0.0 生成数据。

created时间戳是包源首次接收包时的时间戳，通常是目录项的提交时间戳之前的短暂时间。

packageHashAlgorithm是一个由服务器实现定义的字符串，该字符串表示用于生成的哈希算法 packageHash 。 nuget.org 始终使用的 packageHashAlgorithm 值 SHA512 。

packageTypes仅当作者指定了包类型时，才会显示该属性。 如果存在，它将始终至少具有一个（1）条目。 数组中的每一项 packageTypes 都是具有以下属性的 JSON 对象：

名称	类型	必需	说明
name	字符串	是	包类型的名称。
版本	字符串	否	包类型的版本。 只有在作者显式指定了 nuspec 中的版本时，才会出现此情况。

published时间戳是上次列出包的时间。

Note

在 nuget.org 上， published 当包未列出时，该值将设置为1900年。

示例请求

GET https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json

示例响应

[!code-JSON catalog-package-details.json]

包删除目录项

类型为的目录项 PackageDelete 包含一组最小的信息，用于对客户端进行分类，指出包已从包源中删除并且不再可用于任何包操作（如还原）。

Note

包可能会被删除，以后使用相同的包 ID 和版本重新发布。 在 nuget.org 上，这种情况非常罕见，因为它打破了某个包 ID 和版本表示特定包内容的正式客户端假设。 有关 nuget.org 上的包删除的详细信息，请参阅策略。

除了所有目录叶上包含的属性外，包删除目录项还没有其他属性。

version属性是在 nuspec 中找到的原始版本字符串。

published属性是删除包的时间，通常是目录项的提交时间戳之前的短暂时间。

示例请求

GET https://api.nuget.org/v3/catalog0/data/2017.11.02.00.40.00/netstandard1.4_lib.1.0.0-test.json

示例响应

[!code-JSON catalog-package-delete.json]

游标

概述

本部分介绍了尽管协议不一定是由协议强制的客户端概念，但它应是任何实际的目录客户端实现的一部分。

由于目录是按时间编制索引的仅限追加的数据结构，因此客户端应在本地存储游标，这表示客户端处理目录项的时间点。 请注意，此游标值永远不应使用客户端的计算机时钟生成。 相反，该值应来自目录对象的 commitTimestamp 值。

每当客户端想要处理包源上的新事件时，它只需查询其提交时间戳大于其存储游标的所有目录项的目录。 当客户端成功处理所有新的目录项后，它会记录刚刚作为新的游标值处理的目录项的最新提交时间戳。

使用此方法，客户端可以确保永远不会错过包源上发生的任何包事件。 此外，客户端永远不需要在游标记录的提交时间戳之前重新处理旧事件。

这一功能强大的游标概念用于 nuget.org 后台作业，并用于使 V3 API 本身保持最新。

初始值

当目录客户端首次启动时（因此没有游标值），它应使用的默认游标值。NET System.DateTimeOffset.MinValue 或一些这种类似的最小表示时间戳概念。

遍历目录项

若要查询下一组要处理的目录项，客户端应：

1. 从本地存储提取记录的游标值。
2. 下载并反序列化目录索引。
3. 查找提交时间戳大于游标的所有目录页。
4. 声明要处理的目录项的空列表。
5. 对于步骤3中匹配的每个目录页：
   1. 下载并反序列化目录页。
   2. 查找提交时间戳大于游标的所有目录项。
   3. 将所有匹配目录项添加到步骤4中声明的列表。
6. 按提交时间戳对目录项列表进行排序。
7. 按顺序处理每个目录项：
   1. 下载并反序列化目录项。
   2. 对目录项的类型做出适当的反应。
   3. 以客户端特定的方式处理目录项文档。
8. 将最后一个目录项的提交时间戳记录为新的游标值。

使用此基本算法，客户端实现可以生成包源上可用的所有包的完整视图。 客户端只需要定期执行此算法，以便始终了解包源的最新更改。

Note

这是 nuget.org 用于保持包元数据、包内容、搜索和自动完成资源最新的算法。

依赖游标

假设有两个目录客户端具有固有的依赖项，其中一个客户端的输出依赖于另一个客户端的输出。

示例

例如，在 nuget.org 上，新发布的包在包元数据资源中出现之前不应出现在搜索资源中。 这是因为官方 NuGet 客户端执行的 "还原" 操作使用包元数据资源。 如果客户使用搜索服务发现包，他们应该能够使用包元数据资源成功还原该包。 换句话说，搜索资源依赖于包元数据资源。 每个资源都有一个更新该资源的目录客户端后台作业。 每个客户端都有自己的游标。

由于这两个资源都是从目录中生成的，因此，更新搜索资源的目录客户端的游标不得超出包元数据目录客户端的光标。

算法

若要实现此限制，只需将上述算法修改为：

1. 从本地存储提取记录的游标值。
2. 下载并反序列化目录索引。
3. 查找提交时间戳大于或等于依赖项的游标的所有目录页。
4. 声明要处理的目录项的空列表。
5. 对于步骤3中匹配的每个目录页：
   1. 下载并反序列化目录页。
   2. 查找提交时间戳大于或等于依赖项的游标的所有目录项。
   3. 将所有匹配目录项添加到步骤4中声明的列表。
6. 按提交时间戳对目录项列表进行排序。
7. 按顺序处理每个目录项：
   1. 下载并反序列化目录项。
   2. 对目录项的类型做出适当的反应。
   3. 以客户端特定的方式处理目录项文档。
8. 将最后一个目录项的提交时间戳记录为新的游标值。

使用此修改后的算法，可以生成依赖目录客户端的系统，所有这些客户端都生成其自己的特定索引、项目等。