검색

아티클
03/16/2024

V3 API를 사용하여 패키지 원본에서 사용할 수 있는 패키지를 검색할 수 있습니다. 검색에 사용되는 리소스는 서비스 인덱스에서 찾은 리소스입니다SearchQueryService.

버전 관리

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

@type 값	주의
SearchQueryService	초기 릴리스
SearchQueryService/3.0.0-beta	`SearchQueryService`의 별칭
SearchQueryService/3.0.0-rc	`SearchQueryService`의 별칭
SearchQueryService/3.5.0	`packageType` 쿼리 매개 변수 지원 포함

SearchQueryService/3.5.0

이 버전은 쿼리 매개 변수 및 packageTypes 응답 속성에 대한 packageType 지원을 도입하여 작성자가 정의한 패키지 형식을 필터링할 수 있도록 합니다. SearchQueryService에 대한 쿼리 이전 버전과 완전히 호환됩니다.

기준 URL

다음 API의 기본 URL은 afore멘션ed 리소스 @type 값 중 하나와 연결된 속성의 값입니다@id. 다음 문서에서 자리 표시자 기준 URL {@id}이 사용됩니다. 기본 URL은 패키지 원본 내의 구현 또는 인프라 변경에 따라 변경될 수 있으므로 클라이언트 소프트웨어에서 서비스 인덱스에서 동적으로 가져와야 합니다.

HTTP 메서드

등록 리소스에 있는 모든 URL은 HTTP 메서드 GET 및 HEAD를 지원합니다.

패키지 검색

검색 API를 사용하면 클라이언트가 지정된 검색 쿼리와 일치하는 패키지 페이지를 쿼리할 수 있습니다. 검색 쿼리의 해석(예: 검색 용어의 토큰화)은 서버 구현에 의해 결정되지만 일반적으로 검색 쿼리는 패키지 ID, 제목, 설명 및 태그를 일치시키는 데 사용된다는 것입니다. 다른 패키지 메타데이터 필드도 고려될 수 있습니다.

목록에 없는 패키지는 검색 결과에 표시되지 않아야 합니다.

GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}&packageType={PACKAGETYPE}

요청 매개 변수

속성	In	Type	Required	주의
q	URL	string	아니요	패키지를 필터링하는 데 사용할 검색 용어
skip	URL	정수	아니요	페이지 매김을 위해 건너뛸 결과 수
take	URL	정수	아니요	페이지 매김을 위해 반환할 결과 수
시험판	URL	부울 값	아니요	시험판 패키지를 포함시킬지 여부를 결정하는 `true` 또는 `false`
semVerLevel	URL	string	아니요	SemVer 1.0.0 버전 문자열
packageType	URL	string	아니요	패키지를 필터링하는 데 사용할 패키지 형식입니다(`SearchQueryService/3.5.0`에 추가)

검색 쿼리 q 는 서버 구현에 의해 정의된 방식으로 구문 분석됩니다. nuget.org 다양한 필드에 대한 기본 필터링을 지원합니다. 제공되지 않으면 q 모든 패키지가 건너뛰고 가져오기에 의해 부과된 경계 내에서 반환되어야 합니다. 이렇게 하면 NuGet Visual Studio 환경에서 "찾아보기" 탭을 사용할 수 있습니다.

skip 매개 변수의 기본값은 0입니다.

take 매개 변수는 0보다 큰 정수여야 합니다. 서버 구현은 최댓값을 부과할 수 있습니다.

참고 항목

nuget.org 매개 변수를 skip 3,000으로 제한하고 매개 변수를 take 1,000으로 제한합니다.

prerelease를 제공하지 않으면 시험판 패키지가 제외됩니다.

semVerLevel 쿼리 매개 변수는 SemVer 2.0.0 패키지를 옵트인하는 데 사용됩니다. 이 쿼리 매개 변수를 제외하면 SemVer 1.0.0 호환 버전이 있는 패키지만 반환됩니다( 4개의 정수 조각이 있는 버전 문자열과 같은 표준 NuGet 버전 관리 주의 사항 포함). semVerLevel=2.0.0를 제공하면 SemVer 1.0.0 및 SemVer 2.0.0 호환 패키지가 모두 반환됩니다. 자세한 내용은 nuget.org의 SemVer 2.0.0 지원을 참조하세요.

이 packageType 매개 변수는 패키지 형식 이름과 일치하는 패키지 형식이 하나 이상 있는 패키지로만 검색 결과를 추가로 필터링하는 데 사용됩니다. 제공된 패키지 형식이 패키지 형식 문서로 정의된 유효한 패키지 형식이 아닌 경우 빈 결과가 반환됩니다. 제공된 패키지 형식이 비어 있으면 필터가 적용되지 않습니다. 즉, packageType 매개 변수에 값을 전달하지 않으면 매개 변수가 전달되지 않은 것처럼 동작합니다.

응답

응답은 검색 take 결과를 포함하는 JSON 문서입니다. 검색 결과는 패키지 ID별로 그룹화됩니다.

루트 JSON 개체에는 다음 속성이 있습니다.

속성	Type	Required	주의
totalHits	정수	예	`skip` 및 `take`를 무시하는 총 일치 항목 수
데이터	개체의 배열	예	요청과 일치하는 검색 결과

검색 결과

배열의 data 각 항목은 동일한 패키지 ID를 공유하는 패키지 버전 그룹으로 구성된 JSON 개체입니다. 개체의 속성은 다음과 같습니다.

속성	Type	Required	주의
id	string	예	일치하는 패키지의 ID
version	string	예	패키지의 전체 SemVer 2.0.0 버전 문자열(빌드 메타데이터 포함 가능)
description	string	아니요
버전	개체의 배열	예	매개 변수와 일치하는 `prerelease` 패키지의 모든 버전
authors	문자열 또는 문자열 배열	아니요
iconUrl	string	아니요
licenseUrl	string	아니요
owners	문자열 또는 문자열 배열	아니요	문자열은 단일 소유자의 사용자 이름을 나타냅니다.
projectUrl	string	아니요
등록	string	아니요	연결된 등록 인덱스 절대 URL
요약	string	아니요
tags	문자열 또는 문자열 배열	아니요
title	string	아니요
totalDownloads	정수	아니요	이 값은 배열의 다운로드 합계로 유추할 수 있습니다.`versions`
확인	부울 값	아니요	패키지 가 확인되었는지 여부를 나타내는 JSON 부울
packageTypes	개체의 배열	예	패키지 작성자가 정의한 패키지 형식(에 추가 `SearchQueryService/3.5.0`됨)

nuget.org 확인된 패키지는 예약된 ID 접두사와 일치하는 패키지 ID를 가지며 예약된 접두사 소유자 중 하나가 소유하는 패키지입니다. 자세한 내용은 ID 접두사 예약에 대한 설명서를 참조하세요.

검색 결과 개체에 포함된 메타데이터는 최신 패키지 버전에서 가져옵니다. 배열의 versions 각 항목은 다음 속성을 가진 JSON 개체입니다.

속성	Type	Required	주의
@id	string	예	연결된 등록 리프의 절대 URL
version	string	예	패키지의 전체 SemVer 2.0.0 버전 문자열(빌드 메타데이터 포함 가능)
다운로드	정수	예	이 특정 패키지 버전의 다운로드 수

배열은 packageTypes 항상 하나 이상의 (1) 항목으로 구성됩니다. 지정된 패키지 ID의 패키지 형식은 다른 검색 매개 변수와 관련하여 최신 버전의 패키지에서 정의한 패키지 형식으로 간주됩니다. 배열의 packageTypes 각 항목은 다음 속성을 가진 JSON 개체입니다.

속성	Type	Required	주의
name	string	예	패키지 형식의 이름입니다.

샘플 요청

GET https://search-sample.nuget.org/query?q=NuGet.Versioning&prerelease=false&semVerLevel=2.0.0

기본 URL 섹션에 멘션 대로 서비스 인덱스에서 기본 URL(https://search-sample.nuget.org/query이 샘플)을 가져와야 합니다.

샘플 응답

{
  "totalHits": 2,
  "data": [
    {
      "registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.json",
      "id": "NuGet.Versioning",
      "version": "4.4.0",
      "description": "NuGet's implementation of Semantic Versioning.",
      "summary": "",
      "title": "NuGet.Versioning",
      "licenseUrl": "https://raw.githubusercontent.com/NuGet/NuGet.Client/dev/LICENSE.txt",
      "tags": [ "semver", "semantic", "versioning" ],
      "authors": [ "NuGet" ],
      "totalDownloads": 141896,
      "verified": true,
      "packageTypes": [
        {
          "name": "Dependency"
        }
      ],
      "versions": [
        {
          "version": "3.3.0",
          "downloads": 50343,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/3.3.0.json"
        },
        {
          "version": "3.4.3",
          "downloads": 27932,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/3.4.3.json"
        },
        {
          "version": "4.0.0",
          "downloads": 63004,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.0.0.json"
        },
        {
          "version": "4.4.0",
          "downloads": 617,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.4.0.json"
        }
      ]
    },
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/index.json",
      "@type": "Package",
      "registration": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/index.json",
      "id": "Nerdbank.GitVersioning",
      "version": "2.0.41",
      "description": "Stamps your assemblies with semver 2.0 compliant git commit specific version information and provides NuGet versioning information as well.",
      "summary": "Stamps your assemblies with semver 2.0 compliant git commit specific version information and provides NuGet versioning information as well.",
      "title": "Nerdbank.GitVersioning",
      "licenseUrl": "https://raw.githubusercontent.com/AArnott/Nerdbank.GitVersioning/ed547462f7/LICENSE.txt",
      "projectUrl": "http://github.com/aarnott/Nerdbank.GitVersioning",
      "tags": [ "git", "commit", "versioning", "version", "assemblyinfo" ],
      "authors": [ "Andrew Arnott" ],
      "totalDownloads": 11906,
      "verified": false,
      "versions": [
        {
          "version": "1.6.35",
          "downloads": 10229,
          "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/1.6.35.json"
        },
        {
          "version": "2.0.41",
          "downloads": 1677,
          "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/2.0.41.json"
        }
      ]
    }
  ]
}

다음을 통해 공유

검색