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"
}