Dienstindex

Artikel
10/23/2023

Der Dienstindex ist ein JSON-Dokument, das als Einstiegspunkt für eine NuGet-Paketquelle dient und es einer Clientimplementierung ermöglicht, die Funktionen der Paketquelle zu ermitteln. Der Dienstindex ist ein JSON-Objekt mit zwei erforderlichen Eigenschaften: version (die Schemaversion des Dienstindexes) und resources (die Endpunkte oder Funktionen der Paketquelle).

Der Dienstindex von nuget.org befindet sich unter https://api.nuget.org/v3/index.json.

Versionsverwaltung

Der version-Wert ist eine analysierbare SemVer 2.0.0-Versionszeichenfolge, die die Schemaversion des Dienstindexes angibt. Die API verlangt, dass die Versionszeichenfolge die Hauptversionsnummer 3 aufweist. Da am Dienstindexschema keine Breaking Changes vorgenommen werden, wird die Nebenversion der Versionszeichenfolge erhöht.

Jede Ressource im Dienstindex wird unabhängig von der Schemaversion des Dienstindexes mit einer Version versehen.

Die aktuelle Schemaversion lautet 3.0.0. Die Version 3.0.0 entspricht funktional der älteren Version 3.0.0-beta.1, sollte jedoch bevorzugt werden, da sie das stabile, definierte Schema deutlicher darstellt.

HTTP-Methoden

Der Dienstindex ist über die HTTP-Methoden GET und HEAD zugänglich.

Ressourcen

Die Eigenschaft resources enthält ein Array von Ressourcen, die von dieser Paketquelle unterstützt werden.

Resource

Eine Ressource ist ein Objekt im Array resources. Sie stellt eine Funktion einer Paketquelle dar und umfasst eine Versionsangabe. Eine Ressource verfügt über die folgenden Eigenschaften:

Name	Type	Erforderlich	Notizen
@id	Zeichenfolge	ja	Die URL zur Ressource
@type	Zeichenfolge	ja	Eine Zeichenfolgenkonstante, die den Ressourcentyp darstellt
Kommentar	Zeichenfolge	Nein	Lesbare Beschreibung der Ressource

@id ist eine URL, die absolut sein und entweder das HTTP- oder das HTTPS-Schema aufweisen muss.

@type wird verwendet, um das spezifische Protokoll zu identifizieren, das bei der Interaktion mit der Ressource verwendet werden soll. Der Typ der Ressource ist eine nicht transparente Zeichenfolge, weist aber im Allgemeinen das folgende Format auf:

{RESOURCE_NAME}/{RESOURCE_VERSION}

Von Clients wird erwartet, dass sie die interpretierbaren @type-Werte hartcodieren und im Dienstindex einer Paketquelle nachschlagen. Die genauen zurzeit verwendeten @type-Werte werden in den Referenzdokumenten zu den einzelnen Ressourcen aufgeführt, die in der API-Übersicht aufgelistet werden.

Im Rahmen dieser Dokumentation wird die Dokumentation zu verschiedenen Ressourcen im Wesentlichen nach dem im Dienstindex gefundenen {RESOURCE_NAME} gruppiert, was einer Gruppierung nach Szenario entspricht.

Es ist nicht erforderlich, dass jede Ressource über einen eindeutigen @id- oder @type-Wert verfügt. Die Clientimplementierung legt fest, welche Ressource gegenüber einer anderen bevorzugt werden soll. Eine mögliche Implementierung besteht darin, dass Ressourcen desselben oder eines kompatiblen @type-Werts im Falle eines Verbindungs- oder Serverfehlers nach dem Roundrobin-Prinzip verwendet werden können.

Beispielanforderung

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

Beispielantwort

{
  "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."
    }
  ]
}

Freigeben über