Sdílet prostřednictvím


Metadata balíčků

Pomocí rozhraní API NuGet v3 je možné načíst metadata o balíčcích dostupných ve zdroji balíčku. Tato metadata lze načíst pomocí RegistrationsBaseUrl prostředku nalezeného v indexu služby.

Kolekce nalezených dokumentů RegistrationsBaseUrl se často označuje jako "registrace" nebo "objekty blob registrace". Sada dokumentů pod jedním RegistrationsBaseUrl se označuje jako "hive registrace". Registrační podregistr obsahuje metadata o každém balíčku, který je k dispozici ve zdroji balíčku.

Poznámka:

Prostředek metadat balíčku neobsahuje všechna metadata pro balíčky. Pomocí vyhledávacího prostředku můžete vyhledat vlastníky balíčků, soubory ke stažení nebo stav rezervace předpony.

Vytváření verzí

Používají se následující @type hodnoty:

@type Hodnotu Notes
RegistrationsBaseUrl Počáteční verze
RegistrationsBaseUrl/3.0.0-beta Alias of RegistrationsBaseUrl
RegistrationsBaseUrl/3.0.0-rc Alias of RegistrationsBaseUrl
RegistrationsBaseUrl/3.4.0 Odpovědi s Gzipped
RegistrationsBaseUrl/3.6.0 Obsahuje balíčky SemVer 2.0.0.

Představuje tři různé podregistry registrace, které jsou k dispozici pro různé verze klienta.

RegistrationsBaseUrl

Tyto registrace nejsou komprimované (což znamená, že používají implicitní Content-Encoding: identity). Balíčky SemVer 2.0.0 jsou z tohoto hivu vyloučené .

RegistrationsBaseUrl/3.4.0

Tyto registrace jsou komprimovány pomocí Content-Encoding: gzip. Balíčky SemVer 2.0.0 jsou z tohoto hivu vyloučené .

RegistrationsBaseUrl/3.6.0

Tyto registrace jsou komprimovány pomocí Content-Encoding: gzip. Balíčky SemVer 2.0.0 jsou součástí tohoto hivu. Další informace o semVer 2.0.0 naleznete v tématu SemVer 2.0.0 podpora pro nuget.org.

Základní adresa URL

Základní adresa URL pro následující rozhraní API je hodnota @id vlastnosti přidružené k výše uvedeným hodnotám prostředků @type . V následujícím dokumentu se použije zástupná základní adresa URL {@id} . Základní adresa URL se může změnit na základě změn implementace nebo infrastruktury ve zdroji balíčku, takže se musí dynamicky načítat z indexu služby klientským softwarem.

Metody HTTP

Všechny adresy URL nalezené v prostředku registrace podporují metody GET HTTP a HEAD.

Index registrace

Registrační prostředky seskupují metadata balíčku podle ID balíčku. Není možné získat data o více než jednom ID balíčku najednou. Tento prostředek neposkytuje žádný způsob, jak zjistit ID balíčků. Místo toho se předpokládá, že klient už zná id požadovaného balíčku. Dostupná metadata o jednotlivých verzích balíčků se liší podle implementace serveru. Objekty blob registrace balíčku mají následující hierarchickou strukturu:

  • Index: vstupní bod metadat balíčku, který sdílí všechny balíčky ve zdroji se stejným ID balíčku.
  • Stránka: seskupení verzí balíčků. Počet verzí balíčků na stránce je definován implementací serveru.
  • List: dokument specifický pro jednu verzi balíčku.

Adresa URL indexu registrace je předvídatelná a klient může určit ID balíčku a hodnotu registračního prostředku @id z indexu služby. Adresy URL registračních stránek a listů se zjistí kontrolou indexu registrace.

Registrační stránky a listy

I když není nezbytně nutné, aby implementace serveru ukládala listy registrace do samostatných registračních stránek dokumentů, doporučuje se šetřit paměť na straně klienta. Místo vložení všech registrací do indexu nebo okamžitého uložení listů do stránkových dokumentů se doporučuje, aby implementace serveru definovala několik heuristických metod, aby si zvolila mezi těmito dvěma přístupy na základě počtu verzí balíčku nebo kumulativní velikosti listů balíčku.

Uložení všech verzí balíčků (ponechá) v indexu registrace šetří počet požadavků HTTP potřebných k načtení metadat balíčku, ale znamená to, že se musí stáhnout větší dokument a musí být přiděleno více paměti klienta. Na druhou stranu, pokud implementace serveru okamžitě ukládá registrace listy v samostatných stránkových dokumentech, klient musí provádět více požadavků HTTP, aby získal informace, které potřebuje.

Heuristika, kterou nuget.org používá, je následující: pokud existuje 128 nebo více verzí balíčku, rozdělte listy na stránky velikosti 64. Pokud existuje méně než 128 verzí, vložte všechny listy do indexu registrace. Všimněte si, že to znamená, že balíčky s verzí 65 až 127 budou mít v indexu dvě stránky, ale obě stránky budou vloženy.

GET {@id}/{LOWER_ID}/index.json

Parametry požadavku

Název V Typ Požaduje se Notes
LOWER_ID URL string ano ID balíčku, s nižšími písmeny

Hodnota LOWER_ID je ID požadovaného balíčku s dolními písmeny pomocí pravidel implementovaných . System.String.ToLowerInvariant() Metoda NET.

Response

Odpověď je dokument JSON, který má kořenový objekt s následujícími vlastnostmi:

Name Type Požaduje se Notes
count integer ano Počet registračních stránek v indexu
položky pole objektů ano Pole registračních stránek

Každá položka v poli indexového objektu items je objekt JSON představující registrační stránku.

Objekt registrační stránky

Objekt registrační stránky nalezený v indexu registrace má následující vlastnosti:

Name Type Požaduje se Notes
@id string ano Adresa URL registrační stránky
count integer ano Počet opuštění registrace na stránce
položky pole objektů ne Pole registrací opustí a jejich přidružená metadata.
Nižší string ano Nejnižší verze SemVer 2.0.0 na stránce (včetně)
parent string ne Adresa URL indexu registrace
Horní string ano Nejvyšší verze SemVer 2.0.0 na stránce (včetně)

Hranice lower objektu upper stránky jsou užitečné, když jsou potřebná metadata pro konkrétní verzi stránky. Tyto hranice lze použít k načtení jediné požadované registrační stránky. Řetězce verzí dodržují pravidla verzí NuGetu. Řetězce verzí se normalizují a neobsahují metadata sestavení. Stejně jako u všech verzí v ekosystému NuGet se porovnávání řetězců verzí implementuje pomocí pravidel priority verzí se systémem SemVer 2.0.0.

Vlastnost parent se zobrazí pouze v případě, že objekt registrační stránky má items vlastnost.

items Pokud vlastnost není přítomna v objektu registrační stránky, adresa URL zadaná v souboru @id musí být použita k načtení metadat o jednotlivých verzích balíčků. Pole items je někdy vyloučeno z objektu stránky jako optimalizace. Pokud je počet verzí jednoho ID balíčku velmi velký, bude dokument indexu registrace obrovský a plýtvání procesem pro klienta, který se stará pouze o konkrétní verzi nebo malý rozsah verzí.

Všimněte si, že pokud items je vlastnost přítomna, @id nemusí být použita, protože všechna data stránky jsou již vložena do items vlastnosti.

Každá položka v poli objektu items stránky je objekt JSON představující list registrace a přidružená metadata.

Objekt list registrace na stránce

Objekt list registrace nalezený na stránce registrace má následující vlastnosti:

Name Type Požaduje se Notes
@id string ano Adresa URL registračního listu
catalogEntry objekt ano Položka katalogu obsahující metadata balíčku
packageContent string ano Adresa URL obsahu balíčku (.nupkg)

Každý objekt typu list registrace představuje data přidružená k jedné verzi balíčku.

Položka katalogu

Vlastnost catalogEntry v objektu list registrace má následující vlastnosti:

Name Type Požaduje se Notes
@id string ano Adresa URL dokumentu použitého k vytvoření tohoto objektu
Autoři řetězec nebo pole řetězců ne
dependencyGroups pole objektů ne Závislosti balíčku seskupené podle cílové architektury
Odmítání objekt ne Vyřazení přidružené k balíčku
description string ne
iconUrl string ne
ID string ano ID balíčku
jazyk string ne
licenseUrl string ne
licenseExpression string ne
uvedené v seznamu boolean ne Měla by být považována za uvedená, pokud chybí
minClientVersion string ne
packageContent string ne Duplikát stejné vlastnosti v nadřazeného objektu, zahrnutý pouze z důvodu starší verze
projectUrl string ne
Zveřejněna string ne Řetězec obsahující časové razítko ISO 8601 při publikování balíčku
readmeUrl string ne Adresa URL vykresleného zobrazení (webová stránka HTML) souboru README balíčku
requireLicenseAcceptance boolean ne
Souhrn string ne
značky řetězec nebo pole řetězců ne
title string ne
version string ano Řetězec úplné verze po normalizaci
Chyby zabezpečení pole objektů ne Ohrožení zabezpečení balíčku

Vlastnost balíčku version je řetězec úplné verze po normalizaci. To znamená, že semVer 2.0.0 může obsahovat data sestavení.

Vlastnost dependencyGroups je pole objektů představujících závislosti balíčku seskupené podle cílové architektury. Pokud balíček nemá žádné závislosti, dependencyGroups vlastnost chybí, prázdné pole nebo dependencies vlastnost všech skupin je prázdná nebo chybí.

Hodnota vlastnosti odpovídá syntaxi výrazu licenseExpression licence NuGet.

Poznámka:

Při nuget.org je hodnota nastavena na rok 1900, published pokud balíček není v seznamu.

Skupina závislostí balíčků

Každý objekt skupiny závislostí má následující vlastnosti:

Name Type Požaduje se Notes
Targetframework string ne Cílová architektura, na kterou se tyto závislosti vztahují
závislosti pole objektů ne

Řetězec targetFramework používá formát implementovaný knihovnou NuGet.Frameworks knihovny NuGet.Framework nuGet. Pokud není zadána žádná targetFramework hodnota, skupina závislostí se vztahuje na všechny cílové architektury.

Vlastnost dependencies je pole objektů, z nichž každý představuje závislost balíčku aktuálního balíčku.

Závislost balíčku

Každá závislost balíčku má následující vlastnosti:

Name Type Požaduje se Notes
ID string ano ID závislosti balíčku
range objekt ne Povolený rozsah verzí závislosti
registrace string ne Adresa URL indexu registrace pro tuto závislost

range Pokud je vlastnost vyloučena nebo prázdný řetězec, měl by klient výchozí hodnotu rozsahu (, )verzí . To znamená, že je povolená jakákoli verze závislosti. Hodnota * vlastnosti není povolena range .

Vyřazení balíčku

Vyřazení každého balíčku má následující vlastnosti:

Name Type Požaduje se Notes
Důvodů pole řetězců ano Důvody, proč byl balíček zastaralý
zpráva string ne Další podrobnosti o tomto vyřazení
alternatePackage objekt ne Alternativní balíček, který by se měl použít

Vlastnost reasons musí obsahovat alespoň jeden řetězec a měla by obsahovat pouze řetězce z následující tabulky:

Důvod Popis
Starší verze Balíček se už neudržuje.
CriticalBugs Balíček obsahuje chyby, kvůli kterým není vhodné pro použití.
Jiný důvod Balíček je zastaralý kvůli důvodu, který není v tomto seznamu.

reasons Pokud vlastnost obsahuje řetězce, které nejsou ze známé sady, měly by být ignorovány. Řetězce nerozlišují malá a velká písmena, takže legacy by měly být považovány za stejné jako Legacy. U pole neexistuje žádné omezení řazení, takže řetězce mohou být uspořádány v libovolném pořadí. Navíc pokud vlastnost obsahuje pouze řetězce, které nejsou ze známé sady, měla by být považována za to, že obsahovala pouze řetězec "Jiné".

Alternativní balíček

Alternativní objekt balíčku má následující vlastnosti:

Name Type Požaduje se Notes
ID string ano ID alternativního balíčku
range objekt ne Povolený rozsah verzí nebo * pokud je povolená nějaká verze

Ohrožení zabezpečení

Pole vulnerability objektů. Každé ohrožení zabezpečení má následující vlastnosti:

Name Type Požaduje se Notes
advisoryUrl string ano Umístění poradce pro zabezpečení balíčku
závažnost string ano Závažnost poradenství: "0" = Nízká, "1" = Střední, "2" = Vysoká, "3" = Kritická

Ukázkový požadavek

GET https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json

Nezapomeňte načíst základní adresu URL (https://api.nuget.org/v3/registration-sample/ v této ukázce) z indexu služby, jak je uvedeno v části základní adresy URL .

Ukázková odpověď

{
  "count": 1,
  "items": [
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json#page/3.0.0-beta/3.0.0-beta",
      "count": 1,
      "items": [
        {
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/3.0.0-beta.json",
          "catalogEntry": {
            "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json",
            "authors": ".NET Foundation",
            "dependencyGroups": [
              {
                "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup",
                "dependencies": [
                  {
                    "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup/nuget.core",
                    "id": "NuGet.Core",
                    "range": "[2.14.0, )",
                    "registration": "https://api.nuget.org/v3/registration-sample/nuget.core/index.json"
                  }
                ]
              }
            ],
            "description": "Core library for creating a Web Application used to host a simple NuGet feed",
            "iconUrl": "",
            "id": "NuGet.Server.Core",
            "language": "",
            "licenseUrl": "https://raw.githubusercontent.com/NuGet/NuGet.Server/dev/LICENSE.txt",
            "listed": true,
            "minClientVersion": "2.6",
            "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg",
            "projectUrl": "https://github.com/NuGet/NuGet.Server",
            "published": "2017-10-05T18:40:32.43+00:00",
            "requireLicenseAcceptance": false,
            "summary": "",
            "tags": [ "" ],
            "title": "",
            "version": "3.0.0-beta",
            "vulnerabilities": [
              {
                "advisoryUrl": "https://github.com/advisories/ABCD-1234-5678-9012",
                "severity": "2"
              }
            ]
          },
          "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg",
          "registration": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json"
        }
      ],
      "lower": "3.0.0-beta",
      "upper": "3.0.0-beta"
    }
  ]
}

V tomto konkrétním případě má index registrace stránku registrace vloženou, takže k načtení metadat o jednotlivých verzích balíčků nejsou potřeba žádné další požadavky.

Registrační stránka

Registrační stránka obsahuje listy registrace. Adresa URL pro načtení registrační stránky je určena @id vlastností v objektu registrační stránky uvedené výše. Adresa URL není předvídatelná a měla by být vždy zjištěna pomocí indexového dokumentu.

Upozorňující

V nuget.org adresa URL dokumentu registrační stránky shodou okolností obsahuje dolní a horní mez stránky. Tento předpoklad by však nikdy neměl provádět klient, protože implementace serveru mohou změnit tvar adresy URL, pokud má indexový dokument platný odkaz.

items Pokud pole není k dispozici v indexu registrace, požadavek HTTP GET hodnoty @id vrátí dokument JSON, který má objekt jako jeho kořen. Objekt má následující vlastnosti:

Name Type Požaduje se Notes
@id string ano Adresa URL registrační stránky
count integer ano Počet opuštění registrace na stránce
položky pole objektů ano Pole registrací opustí a jejich přidružená metadata.
Nižší string ano Nejnižší verze SemVer 2.0.0 na stránce (včetně)
parent string ano Adresa URL indexu registrace
Horní string ano Nejvyšší verze SemVer 2.0.0 na stránce (včetně)

Tvar registračních objektů typu list je stejný jako v indexu registrace výše.

Ukázkový požadavek

GET https://api.nuget.org/v3/registration-sample/ravendb.client/page/1.0.531/1.0.729-unstable.json

Nezapomeňte načíst základní adresu URL (https://api.nuget.org/v3/registration-sample/ v této ukázce) z indexu služby, jak je uvedeno v části základní adresy URL .

Ukázková odpověď

{
  "count": 2,
  "lower": "1.0.531",
  "parent": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json",
  "upper": "1.0.729-unstable",
  "items": [
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.531.json",
      "@type": "Package",
      "commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1",
      "commitTimeStamp": "2017-10-26T14:12:19.3439088Z",
      "catalogEntry": {
        "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.38.37/nuget.protocol.v3.example.1.0.531.json",
        "@type": "PackageDetails",
        "authors": "NuGet.org Team",
        "iconUrl": "https://www.nuget.org/Content/gallery/img/default-package-icon.svg",
        "id": "NuGet.Protocol.V3.Example",
        "licenseUrl": "http://www.opensource.org/licenses/ms-pl",
        "listed": false,
        "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg",
        "projectUrl": "https://github.com/NuGet/NuGetGallery",
        "published": "1900-01-01T00:00:00+00:00",
        "requireLicenseAcceptance": true,
        "title": "NuGet V3 Protocol Example",
        "version": "1.0.531"
      },
      "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg",
      "registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json"
    },
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.729-unstable.json",
      "@type": "Package",
      "commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1",
      "commitTimeStamp": "2017-10-26T14:12:19.3439088Z",
      "catalogEntry": {
        "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.18.22.05/nuget.protocol.v3.example.1.0.729-unstable.json",
        "@type": "PackageDetails",
        "authors": "NuGet.org Team",
        "deprecation": {
          "reasons": [
            "CriticalBugs"
          ],
          "message": "This package is unstable and broken!",
          "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",
        "licenseUrl": "http://www.opensource.org/licenses/ms-pl",
        "listed": false,
        "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg",
        "projectUrl": "https://github.com/NuGet/NuGetGallery",
        "published": "1900-01-01T00:00:00+00:00",
        "requireLicenseAcceptance": true,
        "summary": "This package is an example for the V3 protocol.",
        "title": "NuGet V3 Protocol Example",
        "version": "1.0.729-Unstable"
      },
      "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg",
      "registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json"
    }
  ]
}

List registrace

List registrace obsahuje informace o konkrétním ID a verzi balíčku. Metadata o konkrétní verzi nemusí být v tomto dokumentu dostupná. Metadata balíčku by se měla načíst z indexu registrace nebo ze stránky registrace (která se zjistí pomocí indexu registrace).

Adresa URL pro načtení registračního listu se získá z @id vlastnosti objektu typu list registrace na registračním indexu nebo registrační stránce. Stejně jako u dokumentu stránky. adresa URL není předvídatelná a měla by být vždy zjištěna pomocí objektu registrační stránky.

Upozorňující

V nuget.org adresa URL dokumentu typu list registrace obsahuje shodou okolností verzi balíčku. Tento předpoklad by však nikdy neměl provádět klient, protože implementace serveru mohou změnit tvar adresy URL, pokud má nadřazený dokument platný odkaz.

List registrace je dokument JSON s kořenovým objektem s následujícími vlastnostmi:

Name Type Požaduje se Notes
@id string ano Adresa URL registračního listu
catalogEntry string ne Adresa URL položky katalogu, která vytvořila tento list
uvedené v seznamu boolean ne Měla by být považována za uvedená, pokud chybí
packageContent string ne Adresa URL obsahu balíčku (.nupkg)
Zveřejněna string ne Řetězec obsahující časové razítko ISO 8601 při publikování balíčku
registrace string ne Adresa URL indexu registrace

Poznámka:

Při nuget.org je hodnota nastavena na rok 1900, published pokud balíček není v seznamu.

Ukázkový požadavek

GET https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json

Nezapomeňte načíst základní adresu URL (https://api.nuget.org/v3/registration-sample/ v této ukázce) z indexu služby, jak je uvedeno v části základní adresy URL .

Ukázková odpověď

{
  "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json",
  "catalogEntry": "https://api.nuget.org/v3/catalog0/data/2017.08.11.18.24.22/nuget.versioning.4.3.0.json",
  "listed": true,
  "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.versioning/4.3.0/nuget.versioning.4.3.0.nupkg",
  "published": "2017-08-11T18:24:14.36+00:00",
  "registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.json"
}