NuGet 서버 API

  • 아티클

NuGet Server API는 패키지를 다운로드하고, 메타데이터를 가져오고, 새 패키지를 게시하고, 공식 NuGet 클라이언트에서 사용할 수 있는 대부분의 다른 작업을 수행하는 데 사용할 수 있는 HTTP 엔드포인트 집합입니다.

이 API는 Visual Studio, nuget.exe 및 .NET CLI의 NuGet 클라이언트에서 Visual Studio UInuget.exe push에서 검색 및 같은 NuGet 작업을 dotnet restore수행하는 데 사용됩니다.

경우에 따라 nuget.org 다른 패키지 원본에 의해 적용되지 않는 추가 요구 사항이 있습니다. 이러한 차이점은 nuget.org 프로토콜에 의해 문서화됩니다.

사용 가능한 nuget.exe 버전의 간단한 열거 및 다운로드는 tools.json 엔드포인트를 참조하세요.

NuGet 패키지 리포지토리를 구현하는 경우 추가 요구 사항 및 권장 사항에 대한 구현 가이드도 참조하세요.

인덱스 제공

API의 진입점은 잘 알려진 위치에 있는 JSON 문서입니다. 이 문서를 서비스 인덱스라고 합니다. nuget.org 대한 서비스 인덱스의 위치입니다 https://api.nuget.org/v3/index.json.

이 JSON 문서에는 다양한 기능을 제공하고 다양한 사용 사례를 충족하는 리소스 목록이 포함되어 있습니다.

API를 지원하는 클라이언트는 해당 패키지 원본에 연결하는 수단으로 이러한 서비스 인덱스 URL 중 하나 이상을 수락해야 합니다.

서비스 인덱스에 대한 자세한 내용은 해당 API 참조를 참조하세요.

버전 관리

API는 NuGet HTTP 프로토콜의 버전 3입니다. 이 프로토콜을 "V3 API"라고도 합니다. 이러한 참조 문서는 이 버전의 프로토콜을 단순히 "API"라고 합니다.

서비스 인덱스 스키마 버전은 서비스 인덱스 속성 version 으로 표시됩니다. API는 버전 문자열에 3의 주 버전 번호를 요구합니다. 서비스 인덱스 스키마에 대해 작업을 중단하지 않는 변경이 적용됨에 따라 버전 문자열의 부 버전이 증가합니다.

이전 클라이언트(예: nuget.exe 2.x)는 V3 API를 지원하지 않으며 여기에 문서화되지 않은 이전 V2 API만 지원합니다.

NuGet V3 API는 공식 NuGet 클라이언트의 2.x 버전에서 구현한 OData 기반 프로토콜인 V2 API의 후속 버전이기 때문에 이름이 지정됩니다. V3 API는 3.0 버전의 공식 NuGet 클라이언트에서 처음 지원되었으며 여전히 NuGet 클라이언트 4.0 이상에서 지원되는 최신 주 프로토콜 버전입니다.

API가 처음 릴리스된 이후 호환되지 않는 프로토콜 변경이 이루어졌습니다.

리소스 및 스키마

서비스 인덱스는 다양한 리소스를 설명합니다. 현재 지원되는 리소스 집합은 다음과 같습니다.

리소스 이름 Required 설명
카탈로그 아니요 모든 패키지 이벤트의 전체 레코드입니다.
PackageBaseAddress 예 패키지 콘텐츠(.nupkg)를 가져옵니다.
PackageDetailsUriTemplate 아니요 패키지 세부 정보 웹 페이지에 액세스하는 URL을 생성합니다.
PackagePublish 예 패키지를 푸시 및 삭제(또는 목록 해제)합니다.
RegistrationsBaseUrl 예 패키지 메타데이터를 가져옵니다.
ReportAbuseUriTemplate 아니요 보고서 남용 웹 페이지에 액세스하는 URL을 생성합니다.
RepositorySignatures 아니요 리포지토리 서명에 사용되는 인증서를 가져옵니다.
SearchAutocompleteService 아니요 부분 문자열을 사용하여 패키지 ID 및 버전을 검색합니다.
SearchQueryService 예 키워드(keyword) 패키지를 필터링하고 검색합니다.
SymbolPackagePublish 아니요 기호 패키지를 푸시합니다.
VulnerabilityInfo 아니요 알려진 취약성이 있는 패키지입니다.

일반적으로 API 리소스에서 반환된 모든 비이진 데이터는 JSON을 사용하여 직렬화됩니다. 서비스 인덱스 내 각 리소스에서 반환되는 응답 스키마는 해당 리소스에 대해 개별적으로 정의됩니다. 각 리소스에 대한 자세한 내용은 위에 나열된 항목을 참조하세요.

나중에 프로토콜이 발전함에 따라 JSON 응답에 새 속성이 추가될 수 있습니다. 클라이언트가 미래 대비를 위해 구현은 응답 스키마가 최종이며 추가 데이터를 포함할 수 없다고 가정해서는 안 됩니다. 구현에서 이해하지 못하는 모든 속성은 무시해야 합니다.

참고 항목

원본에서 자동 완성 동작을 구현 SearchAutocompleteService 하지 않는 경우 정상적으로 사용하지 않도록 설정해야 합니다. ReportAbuseUriTemplate 구현되지 않으면 공식 NuGet 클라이언트가 nuget.org의 보고서 남용 URL(NuGet/Home#4924에서 추적)으로 대체됩니다. 다른 클라이언트는 사용자에게 보고서 남용 URL을 표시하지 않도록 선택할 수 있습니다.

nuget.org 문서화되지 않은 리소스

nuget.org V3 서비스 인덱스에는 위에 설명되지 않은 일부 리소스가 있습니다. 리소스를 문서화하지 않는 몇 가지 이유가 있습니다.

먼저 nuget.org 구현 세부 정보로 사용되는 리소스를 문서화하지 않습니다. 이 SearchGalleryQueryService 범주에 속합니다. NuGetGallery 는 이 리소스를 사용하여 데이터베이스를 사용하는 대신 일부 V2(OData) 쿼리를 검색 인덱스에 위임합니다. 이 리소스는 확장성을 위해 도입되었으며 외부 사용을 위한 것이 아닙니다.

둘째, 공식 클라이언트의 RTM 버전에서 제공되지 않는 리소스는 문서화하지 않습니다. PackageDisplayMetadataUriTemplate 이 PackageVersionDisplayMetadataUriTemplate 범주에 속합니다.

셋째, 의도적으로 문서화되지 않은 V2 프로토콜과 긴밀하게 결합된 리소스는 문서화하지 않습니다. 리소스는 LegacyGallery 이 범주에 속합니다. 이 리소스를 사용하면 V3 서비스 인덱스가 해당 V2 원본 URL을 가리킬 수 있습니다. 이 리소스는 .를 nuget.exe list지원합니다.

여기에 리소스가 문서화되지 않은 경우 리소스에 대한 종속성을 사용하지 않는 것이 좋습니다. 예기치 않은 방법으로 구현을 중단시킬 수 있는 문서화되지 않은 이러한 리소스의 동작을 제거하거나 변경할 수 있습니다.

타임스탬프

API에서 반환된 모든 타임스탬프는 UTC이거나 ISO 8601 표현을 사용하여 지정됩니다.

HTTP 메서드

동사 사용
GET 일반적으로 데이터를 검색하는 읽기 전용 작업을 수행합니다.
HEAD 해당 GET 요청에 대한 응답 헤더를 가져옵니다.
PUT 존재하지 않는 리소스를 만들거나 리소스가 있는 경우 업데이트합니다. 일부 리소스는 업데이트를 지원하지 않을 수 있습니다.
Delete 리소스를 삭제하거나 목록을 해제합니다.

HTTP 상태 코드

코드 설명
200 성공 및 응답 본문이 있습니다.
201 성공하고 리소스를 만들었습니다.
202 성공하면 요청이 수락되었지만 일부 작업은 아직 불완전하고 비동기적으로 완료될 수 있습니다.
204 성공하지만 응답 본문은 없습니다.
301 영구 리디렉션입니다.
302 임시 리디렉션입니다.
400 URL 또는 요청 본문의 매개 변수가 잘못되었습니다.
401 제공된 자격 증명이 잘못되었습니다.
403 제공된 자격 증명을 지정하면 작업이 허용되지 않습니다.
404 요청된 리소스가 없습니다.
409 요청이 기존 리소스와 충돌합니다.
500 서비스에 예기치 않은 오류가 발생했습니다.
503 서비스를 일시적으로 사용할 수 없습니다.

API 엔드포인트에 대한 모든 GET 요청은 HTTP 리디렉션(301 또는 302)을 반환할 수 있습니다. 클라이언트는 헤더를 관찰 Location 하고 후속 GET리디렉션을 실행하여 이러한 리디렉션을 정상적으로 처리해야 합니다. 특정 엔드포인트에 관한 설명서는 리디렉션을 사용할 수 있는 위치를 명시적으로 호출하지 않습니다.

500 수준 상태 코드의 경우 클라이언트는 합리적인 재시도 메커니즘을 구현할 수 있습니다. 공식 NuGet 클라이언트는 500 수준 상태 코드 또는 TCP/DNS 오류가 발생할 때 세 번 다시 시도합니다.

HTTP 요청 헤더

속성 설명
X-NuGet-ApiKey 푸시 및 삭제에 필요, 리소스 참조 PackagePublish
X-NuGet-Client-Version 더 이상 사용되지 않으며 다음으로 대체됨 X-NuGet-Protocol-Version
X-NuGet-Protocol-Version 특정 경우에는 nuget.org 필요한 경우 nuget.org 프로토콜을 참조 하세요.
X-NuGet-Session-Id 선택 사항. NuGet 클라이언트 v4.7 이상은 동일한 NuGet 클라이언트 세션의 일부인 HTTP 요청을 식별합니다.

의 X-NuGet-Session-Id 단일 복원과 관련된 모든 작업에 대한 단일 값이 있습니다 PackageReference. 자동 완성 및 복원과 packages.config 같은 다른 시나리오의 경우 코드가 고려되는 방식 때문에 여러 세션 ID가 다를 수 있습니다.

인증

인증은 정의할 패키지 원본 구현에 남아 있습니다. nuget.org 경우 리소스만 PackagePublish 특수 API 키 헤더를 통한 인증이 필요합니다. 자세한 내용은 리소스를 참조하세요.PackagePublish