영어로 읽기

다음을 통해 공유


카탈로그

카탈로그는 만들기 및 삭제와 같은 패키지 원본의 모든 패키지 작업을 기록하는 리소스입니다. 카탈로그 리소스의 형식은 Catalog 서비스 인덱스입니다. 이 리소스를 사용하여 게시된 모든 패키지를 쿼리할 수 있습니다.

참고

카탈로그는 공식 NuGet 클라이언트에서 사용되지 않으므로 모든 패키지 원본이 카탈로그를 구현하는 것은 아닙니다.

참고

현재 nuget.org 카탈로그는 중국에서 사용할 수 없습니다. 자세한 내용은 NuGet/NuGetGallery#4949를 참조하세요.

버전 관리

다음 @type 값이 사용됩니다.

@type 값 주의
Catalog/3.0.0 초기 릴리스

기준 URL

다음 API의 진입점 URL은 afore멘션ed 리소스 @type 값과 연결된 속성의 값입니다@id. 이 항목에서는 자리 표시자 URL {@id}을 사용합니다.

HTTP 메서드

카탈로그 리소스에 있는 모든 URL은 HTTP 메서드 GETHEAD.

카탈로그 인덱스

카탈로그 인덱스는 카탈로그 항목 목록이 시간순으로 정렬된 잘 알려진 위치에 있는 문서입니다. 카탈로그 리소스의 진입점입니다.

인덱스는 카탈로그 페이지로 구성됩니다. 각 카탈로그 페이지에는 카탈로그 항목이 포함되어 있습니다. 각 카탈로그 항목은 특정 시점에 단일 패키지와 관련된 이벤트를 나타냅니다. 카탈로그 항목은 패키지 원본에서 생성, 목록에 없음, 다시 나열 또는 삭제된 패키지를 나타낼 수 있습니다. 카탈로그 항목을 시간순으로 처리하여 클라이언트는 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 증가합니다. 이러한 두 속성은 기본적으로 배열의 모든 페이지 commitIdcommitTimeStamp 값에 대한 요약입니다 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 다음 두 값 중 하나가 됩니다.

  1. nuget:PackageDetails: 카탈로그 리프 문서의 형식에 해당 PackageDetails 합니다.
  2. 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 이 문서화되지는 않습니다. 그러나 각 카탈로그 항목에는 다음 두 문자열 형식 값 중 하나만 있습니다.

  1. PackageDetails: 패키지 메타데이터의 스냅샷 나타냅니다.
  2. PackageDelete: 삭제된 패키지를 나타냅니다.

패키지 세부 정보 카탈로그 항목

형식 PackageDetails 이 있는 카탈로그 항목에는 특정 패키지(ID 및 버전 조합)에 대한 패키지 메타데이터의 스냅샷 포함됩니다. 패키지 세부 정보 카탈로그 항목은 패키지 원본에 다음 시나리오가 발생할 때 생성됩니다.

  1. 패키지가 푸시됩니다.
  2. 패키지가 다시 나열됩니다.
  3. 패키지가 목록에 없습니다.
  4. 패키지는 더 이상 사용되지 않습니다.
  5. 패키지는 더 이상 사용되지 않습니다.
  6. 패키지가 재배치됩니다.
  7. 패키지의 취약성 상태 업데이트됩니다.

패키지 리플로는 기본적으로 패키지 자체를 변경하지 않고 기존 패키지의 가짜 푸시를 생성하는 관리 제스처입니다. 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 또는 일부 유사한 개념입니다.

카탈로그 항목 반복

처리할 다음 카탈로그 항목 집합을 쿼리하려면 클라이언트는 다음을 수행해야 합니다.

  1. 로컬 저장소에서 기록된 커서 값을 가져옵니다.
  2. 카탈로그 인덱스 다운로드 및 역직렬화
  3. 커밋 타임스탬프 가 커서보다 큰 모든 카탈로그 페이지를 찾습니다.
  4. 처리할 카탈로그 항목의 빈 목록을 선언합니다.
  5. 3단계에서 일치하는 각 카탈로그 페이지에 대해 다음을 수행합니다.
    1. 카탈로그 페이지를 다운로드하고 역직렬화합니다.
    2. 커밋 타임스탬프 가 커서보다 큰 모든 카탈로그 항목을 찾습니다.
    3. 일치하는 모든 카탈로그 항목을 4단계에서 선언된 목록에 추가합니다.
  6. 커밋 타임스탬프를 기준으로 카탈로그 항목 목록을 정렬합니다.
  7. 각 카탈로그 항목을 순서대로 처리합니다.
    1. 카탈로그 항목을 다운로드하고 역직렬화합니다.
    2. 카탈로그 항목의 유형에 적절하게 반응합니다.
    3. 클라이언트별 방식으로 카탈로그 항목 문서를 처리합니다.
  8. 마지막 카탈로그 항목의 커밋 타임스탬프를 새 커서 값으로 기록합니다.

이 기본 알고리즘을 사용하면 클라이언트 구현이 패키지 원본에서 사용할 수 있는 모든 패키지의 전체 보기를 빌드할 수 있습니다. 클라이언트는 항상 패키지 원본에 대한 최신 변경 내용을 인식하기 위해 주기적으로 이 알고리즘을 실행해야 합니다.

참고

nuget.org 패키지 메타데이터, 패키지 콘텐츠, 검색 및 자동 완성 리소스를 최신 상태로 유지하는 데 사용하는 알고리즘입니다.

종속 커서

한 클라이언트의 출력이 다른 클라이언트의 출력에 종속되는 내재된 종속성이 있는 두 개의 카탈로그 클라이언트가 있다고 가정합니다.

예시

예를 들어 nuget.org 새로 게시된 패키지는 패키지 메타데이터 리소스에 표시되기 전에 검색 리소스에 표시되지 않아야 합니다. 이는 공식 NuGet 클라이언트에서 수행하는 "복원" 작업이 패키지 메타데이터 리소스를 사용하기 때문입니다. 고객이 검색 서비스를 사용하여 패키지를 검색하는 경우 패키지 메타데이터 리소스를 사용하여 해당 패키지를 성공적으로 복원할 수 있어야 합니다. 즉, 검색 리소스는 패키지 메타데이터 리소스에 따라 달라집니다. 각 리소스에는 해당 리소스를 업데이트하는 카탈로그 클라이언트 백그라운드 작업이 있습니다. 각 클라이언트에는 고유한 커서가 있습니다.

두 리소스가 모두 카탈로그에서 빌드되므로 검색 리소스 를 업데이트하는 카탈로그 클라이언트의 커서가 패키지 메타데이터 카탈로그 클라이언트의 커서를 넘어서 는 안 됩니다.

알고리즘

이 제한을 구현하려면 위의 알고리즘을 다음과 같이 수정하면 됩니다.

  1. 로컬 저장소에서 기록된 커서 값을 가져옵니다.
  2. 카탈로그 인덱스 다운로드 및 역직렬화
  3. 커밋 타임스탬프가 커서보다 크거나 종속성의 커서보다 큰 카탈로그 페이지를 모두 찾습니다.
  4. 처리할 카탈로그 항목의 빈 목록을 선언합니다.
  5. 3단계에서 일치하는 각 카탈로그 페이지에 대해 다음을 수행합니다.
    1. 카탈로그 페이지를 다운로드하고 역직렬화합니다.
    2. 커밋 타임스탬프가 종속성의 커서보다 작거나 같은 커밋 타임스탬프가 있는 모든 카탈로그 항목을 찾습니다.
    3. 일치하는 모든 카탈로그 항목을 4단계에서 선언된 목록에 추가합니다.
  6. 커밋 타임스탬프를 기준으로 카탈로그 항목 목록을 정렬합니다.
  7. 각 카탈로그 항목을 순서대로 처리합니다.
    1. 카탈로그 항목을 다운로드하고 역직렬화합니다.
    2. 카탈로그 항목의 유형에 적절하게 반응합니다.
    3. 클라이언트별 방식으로 카탈로그 항목 문서를 처리합니다.
  8. 마지막 카탈로그 항목의 커밋 타임스탬프를 새 커서 값으로 기록합니다.

이 수정된 알고리즘을 사용하여 종속 카탈로그 클라이언트의 시스템을 빌드하여 고유한 특정 인덱스, 아티팩트 등을 생성할 수 있습니다.