Index služby

Článek
12/14/2023

Index služby je dokument JSON, který je vstupním bodem zdroje balíčku NuGet a umožňuje implementaci klienta zjistit možnosti zdroje balíčku. Index služby je objekt JSON se dvěma požadovanými vlastnostmi: version (verze schématu indexu služby) a resources (koncové body nebo možnosti zdroje balíčku).

Index služby nuget.org se nachází na adrese https://api.nuget.org/v3/index.json.

Vytváření verzí

Hodnota version je řetězec parsovatelné verze SemVer 2.0.0, který označuje verzi schématu indexu služby. Rozhraní API vyžaduje, aby řetězec verze má číslo 3hlavní verze . Vzhledem k tomu, že ve schématu indexu služby se neprovedou změny způsobující chybu, zvýší se podverze řetězce verze.

Každý prostředek v indexu služby má verzi nezávisle na verzi schématu indexu služby.

Aktuální verze schématu je 3.0.0. Verze 3.0.0 je funkčně ekvivalentní starší 3.0.0-beta.1 verzi, ale měla by být upřednostňovaná, protože jasněji komunikuje se stabilním definovaným schématem.

Metody HTTP

Index služby je přístupný pomocí metod GET HTTP a HEAD.

Zdroje informací

Vlastnost resources obsahuje pole prostředků podporovaných tímto zdrojem balíčku.

Prostředek

Prostředek je objekt v resources poli. Představuje funkci verze zdroje balíčku. Prostředek má následující vlastnosti:

Name	Type	Požaduje se	Notes
@id	string	ano	Adresa URL prostředku
@type	string	ano	Řetězcová konstanta představující typ prostředku
komentář	string	ne	Popis zdroje čitelný pro člověka

Jedná se @id o adresu URL, která musí být absolutní a musí mít buď schéma HTTP nebo HTTPS.

Slouží @type k identifikaci konkrétního protokolu, který se má použít při interakci s prostředkem. Typ prostředku je neprůrůzný řetězec, ale obecně má formát:

{RESOURCE_NAME}/{RESOURCE_VERSION}

Očekává se, že klienti pevně zakódují @type hodnoty, kterým rozumí, a vyhledávají je v indexu služby zdroje balíčků. Přesné @type hodnoty, které se dnes používají, jsou uvedeny v referenčních dokumentech jednotlivých prostředků uvedených v přehledu rozhraní API.

V zájmu této dokumentace bude dokumentace o různých prostředcích v podstatě seskupena {RESOURCE_NAME} podle indexu služby, který je podobný seskupení podle scénáře.

Neexistuje žádný požadavek, aby každý prostředek má jedinečný @id nebo @type. Záleží na implementaci klienta, aby bylo možné určit, který prostředek má přednost před jiným. Jednou z možných implementací je to, že prostředky stejné nebo kompatibilní @type lze použít v případě selhání připojení nebo chyby serveru pomocí kruhového dotazování.

Ukázkový požadavek

GET https://api.nuget.org/v3/index.json

Ukázková odpověď

{
  "version": "3.0.0",
  "resources": [
    {
      "@id": "https://api.nuget.org/v3-flatcontainer/",
      "@type": "PackageBaseAddress/3.0.0",
      "comment": "Base URL of Azure storage where NuGet package registration info for NET Core is stored, in the format https://api.nuget.org/v3-flatcontainer/{id-lower}/{id-lower}.{version-lower}.nupkg"
    },
    {
      "@id": "https://www.nuget.org/api/v2/package",
      "@type": "PackagePublish/2.0.0"
    },
    {
      "@id": "https://api-v2v3search-0.nuget.org/query",
      "@type": "SearchQueryService/3.0.0-rc",
      "comment": "Query endpoint of NuGet Search service (primary) used by RC clients"
    },
    {
      "@id": "https://api-v2v3search-0.nuget.org/autocomplete",
      "@type": "SearchAutocompleteService/3.0.0-rc",
      "comment": "Autocomplete endpoint of NuGet Search service (primary) used by RC clients"
    },
    {
      "@id": "https://api.nuget.org/v3/registration2/",
      "@type": "RegistrationsBaseUrl/3.0.0-rc",
      "comment": "Base URL of Azure storage where NuGet package registration info is stored used by RC clients. This base URL does not include SemVer 2.0.0 packages."
    }
  ]
}

Sdílet prostřednictvím