카탈로그
카탈로그는 만들기 및 삭제와 같은 패키지 원본의 모든 패키지 작업을 기록하는 리소스입니다. 카탈로그 리소스의 형식은 Catalog
서비스 인덱스입니다. 이 리소스를 사용하여 게시된 모든 패키지를 쿼리할 수 있습니다.
참고
카탈로그는 공식 NuGet 클라이언트에서 사용되지 않으므로 모든 패키지 원본이 카탈로그를 구현하는 것은 아닙니다.
참고
현재 nuget.org 카탈로그는 중국에서 사용할 수 없습니다. 자세한 내용은 NuGet/NuGetGallery#4949를 참조하세요.
다음 @type
값이 사용됩니다.
@type 값 | 주의 |
---|---|
Catalog/3.0.0 | 초기 릴리스 |
다음 API의 진입점 URL은 afore멘션ed 리소스 @type
값과 연결된 속성의 값입니다@id
. 이 항목에서는 자리 표시자 URL {@id}
을 사용합니다.
카탈로그 리소스에 있는 모든 URL은 HTTP 메서드 GET
및 HEAD
.
카탈로그 인덱스는 카탈로그 항목 목록이 시간순으로 정렬된 잘 알려진 위치에 있는 문서입니다. 카탈로그 리소스의 진입점입니다.
인덱스는 카탈로그 페이지로 구성됩니다. 각 카탈로그 페이지에는 카탈로그 항목이 포함되어 있습니다. 각 카탈로그 항목은 특정 시점에 단일 패키지와 관련된 이벤트를 나타냅니다. 카탈로그 항목은 패키지 원본에서 생성, 목록에 없음, 다시 나열 또는 삭제된 패키지를 나타낼 수 있습니다. 카탈로그 항목을 시간순으로 처리하여 클라이언트는 V3 패키지 원본에 있는 모든 패키지의 최신 보기를 빌드할 수 있습니다.
즉, 카탈로그 Blob에는 다음과 같은 계층 구조가 있습니다.
- 인덱스: 카탈로그의 진입점입니다.
- 페이지: 카탈로그 항목의 그룹화입니다.
- 리프: 카탈로그 항목을 나타내는 문서로, 단일 패키지 상태의 스냅샷.
각 카탈로그 개체에는 항목이 카탈로그에 commitTimeStamp
추가된 시기를 나타내는 속성이 있습니다. 카탈로그 항목은 커밋이라는 일괄 처리로 카탈로그 페이지에 추가됩니다. 동일한 커밋의 모든 카탈로그 항목에는 커밋 타임스탬프(commitTimeStamp
) 및 커밋 ID(commitId
)가 동일합니다. 동일한 커밋에 배치된 카탈로그 항목은 패키지 원본에서 동일한 시점 전후에 발생한 이벤트를 나타냅니다. 카탈로그 커밋 내에는 순서가 없습니다.
각 패키지 ID와 버전은 고유하기 때문에 커밋에 둘 이상의 카탈로그 항목이 없습니다. 이렇게 하면 커밋 타임스탬프와 관련하여 단일 패키지의 카탈로그 항목을 항상 명확하게 정렬할 수 있습니다.
에 따라 commitTimeStamp
카탈로그에 대한 커밋이 두 개 이상 있을 수 없습니다. 즉, 이 값 commitId
은 .와 중복됩니다 commitTimeStamp
.
패키지 ID로 인덱싱되는 패키지 메타데이터 리소스와 달리 카탈로그는 시간별로만 인덱싱되고 쿼리할 수 있습니다.
카탈로그 항목은 항상 순차적으로 증가하는 시간순으로 카탈로그에 추가됩니다. 즉, 카탈로그 커밋이 X 시간에 추가되면 X보다 작거나 같은 시간으로 카탈로그 커밋이 추가되지 않습니다.
다음 요청은 카탈로그 인덱스를 가져옵니다.
GET {@id}
카탈로그 인덱스는 다음 속성을 가진 개체를 포함하는 JSON 문서입니다.
속성 | Type | Required | 주의 |
---|---|---|---|
commitId | string | 예 | 가장 최근 커밋과 연결된 고유 ID |
commitTimeStamp | string | 예 | 가장 최근 커밋의 타임스탬프 |
count | 정수 | 예 | 인덱스의 페이지 수 |
항목 | 개체의 배열 | 예 | 페이지를 나타내는 각 개체의 개체 배열입니다. |
배열의 items
각 요소는 각 페이지에 대한 최소한의 세부 정보를 가진 개체입니다. 이러한 페이지 개체는 카탈로그 잎(항목)을 포함하지 않습니다. 이 배열의 요소 순서가 정의되지 않았습니다. 클라이언트는 해당 속성을 사용하여 메모리에서 페이지를 정렬할 수 있습니다 commitTimeStamp
.
새 페이지가 도입되면 count
증분되고 새 개체가 배열에 items
표시됩니다.
항목이 카탈로그에 추가되면 인덱스가 commitId
변경되고 commitTimeStamp
증가합니다. 이러한 두 속성은 기본적으로 배열의 모든 페이지 commitId
와 commitTimeStamp
값에 대한 요약입니다 items
.
카탈로그 인덱스의 items
속성에 있는 카탈로그 페이지 개체에는 다음과 같은 속성이 있습니다.
속성 | Type | Required | 주의 |
---|---|---|---|
@id | string | 예 | 카탈로그 페이지를 가져올 URL |
commitId | string | 예 | 이 페이지의 가장 최근 커밋과 연결된 고유 ID |
commitTimeStamp | string | 예 | 이 페이지에서 가장 최근 커밋의 타임스탬프 |
count | 정수 | 예 | 카탈로그 페이지의 항목 수 |
경우에 따라 인라인이 인덱스로 나가는 패키지 메타데이터 리소스와 달리 카탈로그 리프는 인덱스에 인라인되지 않으며 항상 페이지의 @id
URL을 사용하여 가져와야 합니다.
GET https://api.nuget.org/v3/catalog0/index.json
{
"commitId": "3d698852-eefb-48ed-8f55-9ee357540d20",
"commitTimeStamp": "2017-10-31T23:33:17.0954363Z",
"count": 3,
"items": [
{
"@id": "https://api.nuget.org/v3/catalog0/page0.json",
"commitId": "3a4df280-3d86-458e-a713-4c91ca261fef",
"commitTimeStamp": "2015-02-01T06:30:11.7477681Z",
"count": 540
},
{
"@id": "https://api.nuget.org/v3/catalog0/page1.json",
"commitId": "8bcd3cbf-74f0-47a2-a7ae-b7ecc50005d3",
"commitTimeStamp": "2015-02-01T06:39:53.9553899Z",
"count": 540
},
{
"@id": "https://api.nuget.org/v3/catalog0/page2.json",
"commitId": "3d698852-eefb-48ed-8f55-9ee357540d20",
"commitTimeStamp": "2017-10-31T23:33:17.0954363Z",
"count": 47
}
]
}
카탈로그 페이지는 카탈로그 항목의 컬렉션입니다. 카탈로그 인덱스의 값 중 @id
하나를 사용하여 가져온 문서입니다. 카탈로그 페이지의 URL은 예측할 수 없으며 카탈로그 인덱스만 사용하여 검색해야 합니다.
새 카탈로그 항목은 커밋 타임스탬프가 가장 높은 카탈로그 인덱스 또는 새 페이지에만 페이지에 추가됩니다. 커밋 타임스탬프가 더 높은 페이지가 카탈로그에 추가되면 이전 페이지는 추가되거나 변경되지 않습니다.
카탈로그 페이지 문서는 다음 속성을 가진 JSON 개체입니다.
속성 | Type | Required | 주의 |
---|---|---|---|
commitId | string | 예 | 이 페이지의 가장 최근 커밋과 연결된 고유 ID |
commitTimeStamp | string | 예 | 이 페이지에서 가장 최근 커밋의 타임스탬프 |
count | 정수 | 예 | 페이지의 항목 수 |
항목 | 개체의 배열 | 예 | 이 페이지의 카탈로그 항목 |
parent | string | 예 | 카탈로그 인덱스 URL |
배열의 items
각 요소는 카탈로그 항목에 대한 최소한의 세부 정보를 가진 개체입니다. 이러한 항목 개체에는 카탈로그 항목의 데이터가 모두 포함되지 않습니다. 페이지 배열에 있는 항목의 items
순서가 정의되지 않았습니다. 클라이언트는 해당 속성을 사용하여 메모리에서 항목을 정렬할 commitTimeStamp
수 있습니다.
페이지의 카탈로그 항목 수는 서버 구현에 의해 정의됩니다. nuget.org 경우 각 페이지에 최대 550개의 항목이 있지만 특정 시점에 다음 커밋 일괄 처리의 크기에 따라 일부 페이지의 실제 수가 더 작을 수 있습니다.
새 항목이 도입되면 count
증분되고 새 카탈로그 항목 개체가 배열에 items
표시됩니다.
항목이 페이지에 commitId
추가되면 변경 내용과 증가가 commitTimeStamp
증가합니다. 이러한 두 속성은 기본적으로 배열의 모든 commitId
값과 commitTimeStamp
값에 items
대한 요약입니다.
카탈로그 페이지의 items
속성에 있는 카탈로그 항목 개체에는 다음과 같은 속성이 있습니다.
속성 | Type | Required | 주의 |
---|---|---|---|
@id | string | 예 | 카탈로그 항목을 가져올 URL입니다. |
@type | string | 예 | 카탈로그 항목의 형식입니다. |
commitId | string | 예 | 이 카탈로그 항목과 연결된 커밋 ID |
commitTimeStamp | string | 예 | 이 카탈로그 항목의 커밋 타임스탬프 |
nuget:id | string | 예 | 이 리프와 관련된 패키지 ID |
nuget:version | string | 예 | 이 리프와 관련된 패키지 버전 |
값은 @type
다음 두 값 중 하나가 됩니다.
nuget:PackageDetails
: 카탈로그 리프 문서의 형식에 해당PackageDetails
합니다.nuget:PackageDelete
: 카탈로그 리프 문서의 형식에 해당PackageDelete
합니다.
각 형식의 의미에 대한 자세한 내용은 아래의 해당 항목 유형을 참조하세요.
GET https://api.nuget.org/v3/catalog0/page2926.json
{
"commitId": "616117f5-d9dd-4664-82b9-74d87169bbe9",
"commitTimeStamp": "2017-10-31T23:30:32.4197849Z",
"count": 5,
"parent": "https://api.nuget.org/v3/catalog0/index.json",
"items": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.23.30.32/util.biz.payments.0.0.4-preview.json",
"@type": "nuget:PackageDetails",
"commitId": "616117f5-d9dd-4664-82b9-74d87169bbe9",
"commitTimeStamp": "2017-10-31T23:30:32.4197849Z",
"nuget:id": "Util.Biz.Payments",
"nuget:version": "0.0.4-preview"
},
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.23.28.02/util.biz.0.0.4-preview.json",
"@type": "nuget:PackageDetails",
"commitId": "820340b2-97e3-4f93-b82e-bc85550a6560",
"commitTimeStamp": "2017-10-31T23:28:02.788239Z",
"nuget:id": "Util.Biz",
"nuget:version": "0.0.4-preview"
},
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.22.31.22/sourcecode.clay.data.1.0.0-preview1-00258.json",
"@type": "nuget:PackageDetails",
"commitId": "cae34527-ffc7-4e96-884f-7cf95a32dbdd",
"commitTimeStamp": "2017-10-31T22:31:22.5169519Z",
"nuget:id": "SourceCode.Clay.Data",
"nuget:version": "1.0.0-preview1-00258"
},
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.22.31.22/sourcecode.clay.1.0.0-preview1-00258.json",
"@type": "nuget:PackageDetails",
"commitId": "cae34527-ffc7-4e96-884f-7cf95a32dbdd",
"commitTimeStamp": "2017-10-31T22:31:22.5169519Z",
"nuget:id": "SourceCode.Clay",
"nuget:version": "1.0.0-preview1-00258"
},
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.22.31.22/sourcecode.clay.json.1.0.0-preview1-00258.json",
"@type": "nuget:PackageDetails",
"commitId": "cae34527-ffc7-4e96-884f-7cf95a32dbdd",
"commitTimeStamp": "2017-10-31T22:31:22.5169519Z",
"nuget:id": "SourceCode.Clay.Json",
"nuget:version": "1.0.0-preview1-00258"
}
]
}
카탈로그 리프는 특정 시점에 특정 패키지 ID 및 버전에 대한 메타데이터를 포함합니다. 카탈로그 페이지에 있는 값을 사용하여 @id
가져온 문서입니다. 카탈로그 리프의 URL은 예측할 수 없으며 카탈로그 페이지만 사용하여 검색해야 합니다.
카탈로그 리프 문서는 다음 속성을 가진 JSON 개체입니다.
속성 | Type | Required | 주의 |
---|---|---|---|
@type | 문자열 또는 문자열 배열 | 예 | 카탈로그 항목의 형식입니다. |
catalog:commitId | string | 예 | 이 카탈로그 항목과 연결된 커밋 ID |
catalog:commitTimeStamp | string | 예 | 이 카탈로그 항목의 커밋 타임스탬프 |
id | string | 예 | 카탈로그 항목의 패키지 ID |
published | string | 예 | 패키지 카탈로그 항목의 게시된 날짜 |
version | string | 예 | 카탈로그 항목의 패키지 버전 |
속성은 @type
문자열 또는 문자열의 배열입니다. 편의를 위해 값이 @type
문자열인 경우 크기 1의 배열로 처리해야 합니다. 가능한 모든 값 @type
이 문서화되지는 않습니다. 그러나 각 카탈로그 항목에는 다음 두 문자열 형식 값 중 하나만 있습니다.
PackageDetails
: 패키지 메타데이터의 스냅샷 나타냅니다.PackageDelete
: 삭제된 패키지를 나타냅니다.
형식 PackageDetails
이 있는 카탈로그 항목에는 특정 패키지(ID 및 버전 조합)에 대한 패키지 메타데이터의 스냅샷 포함됩니다. 패키지 세부 정보 카탈로그 항목은 패키지 원본에 다음 시나리오가 발생할 때 생성됩니다.
- 패키지가 푸시됩니다.
- 패키지가 다시 나열됩니다.
- 패키지가 목록에 없습니다.
- 패키지는 더 이상 사용되지 않습니다.
- 패키지는 더 이상 사용되지 않습니다.
- 패키지가 재배치됩니다.
- 패키지의 취약성 상태 업데이트됩니다.
패키지 리플로는 기본적으로 패키지 자체를 변경하지 않고 기존 패키지의 가짜 푸시를 생성하는 관리 제스처입니다. nuget.org 카탈로그를 사용하는 백그라운드 작업 중 하나에서 버그를 수정한 후 다시 흐름이 사용됩니다.
카탈로그 항목을 사용하는 클라이언트는 이러한 시나리오 중 카탈로그 항목을 생성한 시나리오를 확인하려고 시도해서는 안 됩니다. 대신 클라이언트는 카탈로그 항목에 포함된 메타데이터를 사용하여 기본기본이 지정된 뷰 또는 인덱스만 업데이트해야 합니다. 또한 중복 또는 중복 카탈로그 항목을 정상적으로 처리해야 합니다(idempotently).
패키지 세부 정보 카탈로그 항목에는 모든 카탈로그 잎에 포함된 속성 외에도 다음과 같은 속성이 있습니다.
속성 | Type | Required | 주의 |
---|---|---|---|
authors | string | 아니요 | |
created | string | 아니요 | 패키지를 처음 만든 시기의 타임스탬프입니다. 대체 속성: published . |
dependencyGroups | 개체의 배열 | 아니요 | 대상 프레임워크별로 그룹화된 패키지의 종속성(패키지 메타데이터 리소스와 동일한 형식) |
Deprecation | 개체 | 아니요 | 패키지와 연결된 사용 중단(패키지 메타데이터 리소스와 동일한 형식) |
description | string | 아니요 | |
iconUrl | string | 아니요 | |
isPrerelease | 부울 값 | 아니요 | 패키지 버전이 시험판인지 여부입니다. 에서 version 검색할 수 있습니다. |
언어 | string | 아니요 | |
licenseUrl | string | 아니요 | |
나열 | 부울 값 | 아니요 | 패키지가 나열되는지 여부 |
minClientVersion | string | 아니요 | |
packageHash | string | 예 | 표준 base 64를 사용하여 인코딩하는 패키지의 해시 |
packageHashAlgorithm | string | 예 | |
packageSize | 정수 | 예 | 패키지 .nupkg의 크기(바이트)입니다. |
packageTypes | 개체의 배열 | 아니요 | 작성자가 지정한 패키지 형식입니다. |
projectUrl | string | 아니요 | |
releaseNotes | string | 아니요 | |
requireLicenseAgreement | 부울 값 | 아니요 | 제외된 경우 가정 false |
요약 | string | 아니요 | |
tags | 문자열 배열 | 아니요 | |
title | string | 아니요 | |
verbatimVersion | string | 아니요 | .nuspec에서 원래 발견된 버전 문자열입니다. |
취약성 | 개체의 배열 | 아니요 | 패키지의 보안 취약성 |
패키지 version
속성은 정규화 후의 전체 버전 문자열입니다. 즉, SemVer 2.0.0 빌드 데이터를 여기에 포함할 수 있습니다.
created
타임스탬프는 패키지 원본에서 패키지를 처음 받은 시점으로, 일반적으로 카탈로그 항목의 커밋 타임스탬프 이전의 짧은 시간입니다.
서버 packageHashAlgorithm
구현에서 정의한 문자열로, 생성에 사용되는 해시 알고리즘을 packageHash
나타냅니다. nuget.org 항상 값을 SHA512
사용합니다packageHashAlgorithm
.
이 속성은 packageTypes
작성자가 패키지 형식을 지정한 경우에만 존재합니다. 있는 경우 항상 하나 이상의 항목이 있습니다. 배열의 packageTypes
각 항목은 다음 속성을 가진 JSON 개체입니다.
속성 | Type | Required | 주의 |
---|---|---|---|
name | string | 예 | 패키지 형식의 이름입니다. |
version | string | 아니요 | 패키지 유형의 버전입니다. 작성자가 nuspec에서 버전을 명시적으로 지정한 경우에만 존재합니다. |
published
타임스탬프는 패키지가 마지막으로 나열된 시간입니다.
참고
nuget.org 패키지가 published
목록에 없는 경우 값은 1900년으로 설정됩니다.
vulnerability
개체의 배열입니다. 각 취약성에는 다음과 같은 속성이 있습니다.
속성 | Type | Required | 주의 |
---|---|---|---|
advisoryUrl | string | 예 | 패키지의 보안 권고 위치 |
severity | string | 예 | 권고 심각도: "0" = Low, "1" = Moderate, "2" = High, "3" = Critical |
속성에 severity
여기에 나열된 값 이외의 값이 포함된 경우 권고의 심각도는 낮음으로 처리됩니다.
GET https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json
{
"@type": [
"PackageDetails",
"catalog:Permalink"
],
"authors": "NuGet.org Team",
"catalog:commitId": "49fe04d8-5694-45a5-9822-3be61bda871b",
"catalog:commitTimeStamp": "2015-02-01T11:18:40.8589193Z",
"created": "2011-12-02T20:21:23.74Z",
"description": "This package is an example for the V3 protocol.",
"deprecation": {
"reasons": [
"Legacy",
"HasCriticalBugs",
"Other"
],
"message": "This package is an example--it should not be used!",
"alternatePackage": {
"id": "Newtonsoft.JSON",
"range": "12.0.2"
}
},
"iconUrl": "https://www.nuget.org/Content/gallery/img/default-package-icon.svg",
"id": "NuGet.Protocol.V3.Example",
"isPrerelease": false,
"language": "en-US",
"licenseUrl": "http://www.opensource.org/licenses/ms-pl",
"packageHash": "2edCwKLcbcgFJpsAwa883BLtOy8bZpWwbQpiIb71E74k5t2f2WzXEGWbPwntRleUEgSrcxJrh9Orm/TAmgO4NQ==",
"packageHashAlgorithm": "SHA512",
"packageSize": 118348,
"packageTypes": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#packagetypes/DotnetTool",
"@type": "PackageType",
"name": "DotnetTool"
}
],
"projectUrl": "https://github.com/NuGet/NuGetGallery",
"published": "1900-01-01T00:00:00Z",
"requireLicenseAcceptance": false,
"title": "NuGet V3 Protocol Example",
"version": "1.0.0",
"dependencyGroups": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup",
"@type": "PackageDependencyGroup",
"dependencies": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup/aspnet.suppressformsredirect",
"@type": "PackageDependency",
"id": "aspnet.suppressformsredirect",
"range": "[0.0.1.4, )"
},
{
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup/webactivator",
"@type": "PackageDependency",
"id": "WebActivator",
"range": "[1.4.4, )"
},
{
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup/webapi.all",
"@type": "PackageDependency",
"id": "WebApi.All",
"range": "[0.5.0, )"
}
],
"targetFramework": ".NETFramework4.6"
}
],
"tags": [
"NuGet",
"V3",
"Protocol",
"Example"
],
"vulnerabilities": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#vulnerability/GitHub/999",
"@type": "Vulnerability",
"advisoryUrl": "https://github.com/advisories/ABCD-1234-5678-9012",
"severity": "2"
}
]
}
형식 PackageDelete
이 있는 카탈로그 항목은 패키지 원본에서 패키지가 삭제되었으며 패키지 작업(예: 복원)에 더 이상 사용할 수 없음을 카탈로그 클라이언트에 나타내는 최소한의 정보 집합을 포함합니다.
참고
동일한 패키지 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
{
"@type": [
"PackageDelete",
"catalog:Permalink"
],
"catalog:commitId": "19fec5b4-9335-4e4b-bd50-8d5d3f734597",
"catalog:commitTimeStamp": "2017-11-02T00:40:00.1969812Z",
"id": "netstandard1.4_lib",
"originalId": "netstandard1.4_lib",
"published": "2017-11-02T00:37:43.7181952Z",
"version": "1.0.0-test"
}
이 섹션에서는 프로토콜에 의해 반드시 위임되는 것은 아니지만 실제 카탈로그 클라이언트 구현의 일부가 되어야 한다는 클라이언트 개념을 설명합니다.
카탈로그는 시간별로 인덱싱된 추가 전용 데이터 구조이므로 클라이언트는 클라이언트가 카탈로그 항목을 처리한 시점까지 나타내는 커서를 로컬로 저장해야 합니다. 이 커서 값은 클라이언트의 컴퓨터 클록을 사용하여 생성해서는 안 됩니다. 대신 이 값은 카탈로그 개체의 commitTimestamp
값에서 가져옵니다.
클라이언트가 패키지 원본에서 새 이벤트를 처리하려고 할 때마다 커밋 타임스탬프가 저장된 커서보다 큰 모든 카탈로그 항목에 대해서만 카탈로그를 쿼리하면 됩니다. 클라이언트가 모든 새 카탈로그 항목을 성공적으로 처리한 후 새 커서 값으로 처리된 카탈로그 항목의 최신 커밋 타임스탬프를 기록합니다.
이 방법을 사용하면 클라이언트가 패키지 원본에서 발생한 패키지 이벤트를 놓치지 않도록 할 수 있습니다. 또한 클라이언트는 커서의 기록된 커밋 타임스탬프 이전에 이전 이벤트를 다시 처리할 필요가 없습니다.
이 강력한 커서 개념은 많은 nuget.org 백그라운드 작업에 사용되며 V3 API 자체를 최신 상태로 유지하는 데 사용됩니다.
카탈로그 클라이언트가 처음으로 시작하는 경우(따라서 커서 값이 없음) 기본 커서 값을 사용해야 합니다. System.DateTimeOffset.MinValue
최소 표현 가능한 타임스탬프에 대한 NET 또는 일부 유사한 개념입니다.
처리할 다음 카탈로그 항목 집합을 쿼리하려면 클라이언트는 다음을 수행해야 합니다.
- 로컬 저장소에서 기록된 커서 값을 가져옵니다.
- 카탈로그 인덱스 다운로드 및 역직렬화
- 커밋 타임스탬프 가 커서보다 큰 모든 카탈로그 페이지를 찾습니다.
- 처리할 카탈로그 항목의 빈 목록을 선언합니다.
- 3단계에서 일치하는 각 카탈로그 페이지에 대해 다음을 수행합니다.
- 카탈로그 페이지를 다운로드하고 역직렬화합니다.
- 커밋 타임스탬프 가 커서보다 큰 모든 카탈로그 항목을 찾습니다.
- 일치하는 모든 카탈로그 항목을 4단계에서 선언된 목록에 추가합니다.
- 커밋 타임스탬프를 기준으로 카탈로그 항목 목록을 정렬합니다.
- 각 카탈로그 항목을 순서대로 처리합니다.
- 카탈로그 항목을 다운로드하고 역직렬화합니다.
- 카탈로그 항목의 유형에 적절하게 반응합니다.
- 클라이언트별 방식으로 카탈로그 항목 문서를 처리합니다.
- 마지막 카탈로그 항목의 커밋 타임스탬프를 새 커서 값으로 기록합니다.
이 기본 알고리즘을 사용하면 클라이언트 구현이 패키지 원본에서 사용할 수 있는 모든 패키지의 전체 보기를 빌드할 수 있습니다. 클라이언트는 항상 패키지 원본에 대한 최신 변경 내용을 인식하기 위해 주기적으로 이 알고리즘을 실행해야 합니다.
한 클라이언트의 출력이 다른 클라이언트의 출력에 종속되는 내재된 종속성이 있는 두 개의 카탈로그 클라이언트가 있다고 가정합니다.
예를 들어 nuget.org 새로 게시된 패키지는 패키지 메타데이터 리소스에 표시되기 전에 검색 리소스에 표시되지 않아야 합니다. 이는 공식 NuGet 클라이언트에서 수행하는 "복원" 작업이 패키지 메타데이터 리소스를 사용하기 때문입니다. 고객이 검색 서비스를 사용하여 패키지를 검색하는 경우 패키지 메타데이터 리소스를 사용하여 해당 패키지를 성공적으로 복원할 수 있어야 합니다. 즉, 검색 리소스는 패키지 메타데이터 리소스에 따라 달라집니다. 각 리소스에는 해당 리소스를 업데이트하는 카탈로그 클라이언트 백그라운드 작업이 있습니다. 각 클라이언트에는 고유한 커서가 있습니다.
두 리소스가 모두 카탈로그에서 빌드되므로 검색 리소스 를 업데이트하는 카탈로그 클라이언트의 커서가 패키지 메타데이터 카탈로그 클라이언트의 커서를 넘어서 는 안 됩니다.
이 제한을 구현하려면 위의 알고리즘을 다음과 같이 수정하면 됩니다.
- 로컬 저장소에서 기록된 커서 값을 가져옵니다.
- 카탈로그 인덱스 다운로드 및 역직렬화
- 커밋 타임스탬프가 커서보다 크거나 종속성의 커서보다 큰 카탈로그 페이지를 모두 찾습니다.
- 처리할 카탈로그 항목의 빈 목록을 선언합니다.
- 3단계에서 일치하는 각 카탈로그 페이지에 대해 다음을 수행합니다.
- 카탈로그 페이지를 다운로드하고 역직렬화합니다.
- 커밋 타임스탬프가 종속성의 커서보다 작거나 같은 커밋 타임스탬프가 있는 모든 카탈로그 항목을 찾습니다.
- 일치하는 모든 카탈로그 항목을 4단계에서 선언된 목록에 추가합니다.
- 커밋 타임스탬프를 기준으로 카탈로그 항목 목록을 정렬합니다.
- 각 카탈로그 항목을 순서대로 처리합니다.
- 카탈로그 항목을 다운로드하고 역직렬화합니다.
- 카탈로그 항목의 유형에 적절하게 반응합니다.
- 클라이언트별 방식으로 카탈로그 항목 문서를 처리합니다.
- 마지막 카탈로그 항목의 커밋 타임스탬프를 새 커서 값으로 기록합니다.
이 수정된 알고리즘을 사용하여 종속 카탈로그 클라이언트의 시스템을 빌드하여 고유한 특정 인덱스, 아티팩트 등을 생성할 수 있습니다.