Freigeben über

Katalog

  • Artikel

Der Katalog ist eine Ressource, die alle Paketvorgänge in einer Paketquelle aufzeichnet, z. B. Erstellungen und Löschungen. Die Katalogressource weist den Catalog Typ im Dienstindex auf. Sie können diese Ressource verwenden, um alle veröffentlichten Pakete abzufragen.

Hinweis

Da der Katalog nicht vom offiziellen NuGet-Client verwendet wird, implementieren nicht alle Paketquellen den Katalog.

Hinweis

Derzeit ist der nuget.org-Katalog in China nicht verfügbar. Weitere Informationen finden Sie unter NuGet/NuGetGallery#4949.

Versionsverwaltung

Der folgende @type Wert wird verwendet:

Wert vom Typ @type Hinweise
Katalog/3.0.0 Erstrelease

Basis-URL

Die Basis-URL für die folgenden APIs ist der Wert der @id-Eigenschaft, die einem der oben genannten @type-Ressourcenwerte zugeordnet ist. In diesem Thema wird die Platzhalter-URL {@id}verwendet.

HTTP-Methoden

Alle URLs in der Registrierungsressource unterstützen die HTTP-Methoden GET und HEAD.

Katalogindex

Der Katalogindex ist ein Dokument an einem bekannten Speicherort mit einer Liste von Katalogelementen, die chronologisch sortiert sind. Dies ist der Einstiegspunkt der Katalogressource.

Der Index besteht aus Katalogseiten. Jede Katalogseite enthält Katalogelemente. Jedes Katalogelement stellt ein Ereignis für ein einzelnes Paket zu einem Zeitpunkt dar. Ein Katalogelement kann ein Paket darstellen, das erstellt, nicht aufgelistet, erneut aufgelistet oder aus der Paketquelle gelöscht wurde. Durch die Verarbeitung der Katalogelemente in chronologischer Reihenfolge kann der Client eine aktuelle Ansicht aller Pakete erstellen, die in der V3-Paketquelle vorhanden sind.

Kurz gesagt haben Katalog-Blobs die folgende hierarchische Struktur:

  • Index: der Einstiegspunkt für den Katalog.
  • Seite: eine Gruppierung von Katalogelementen.
  • Blatt: Ein Dokument, das ein Katalogelement darstellt, bei dem es sich um eine Momentaufnahme des Zustands eines einzelnen Pakets handelt.

Jedes Katalogobjekt verfügt über eine Eigenschaft, die so commitTimeStamp aufgerufen wird, dass das Element dem Katalog hinzugefügt wurde. Katalogelemente werden einer Katalogseite in Batches hinzugefügt, die als Commits bezeichnet werden. Alle Katalogelemente im gleichen Commit haben den gleichen Commit-Zeitstempel (commitTimeStamp) und commit-ID (commitId). Katalogelemente, die im gleichen Commit platziert wurden, stellen Ereignisse dar, die um denselben Zeitpunkt in der Paketquelle aufgetreten sind. Es gibt keine Sortierung innerhalb eines Katalog-Commits.

Da jede Paket-ID und -Version eindeutig ist, gibt es nie mehr als ein Katalogelement in einem Commit. Dadurch wird sichergestellt, dass Katalogelemente für ein einzelnes Paket immer eindeutig geordnet werden können, um den Zeitstempel zu übernehmen.

Es gibt nie mehr als einen Commit für den Katalog pro commitTimeStamp. Mit anderen Worten, die commitId ist redundant mit der commitTimeStamp.

Im Gegensatz zur Paketmetadatenressource, die von der Paket-ID indiziert wird, wird der Katalog nur nach Zeit indiziert (und abfragbar).

Katalogelemente werden dem Katalog immer in monoton steigender chronologischer Reihenfolge hinzugefügt. Dies bedeutet, dass, wenn ein Katalog-Commit zum Zeitpunkt X hinzugefügt wird, kein Katalog-Commit jemals mit einer Zeit hinzugefügt wird, die kleiner oder gleich X ist.

Die folgende Anforderung ruft den Katalogindex ab.

GET {@id}

Der Katalogindex ist ein JSON-Dokument, das ein Objekt mit den folgenden Eigenschaften enthält:

Name Type Erforderlich Hinweise
commitId Zeichenfolge ja Eine eindeutige ID, die dem letzten Commit zugeordnet ist
commitTimeStamp Zeichenfolge ja Zeitstempel des letzten Commits
count integer ja Anzahl der Seiten im Index
items Array von Objekten ja Ein Array von Objekten, jedes Objekt, das eine Seite darstellt

Jedes Element im items Array ist ein Objekt mit minimalen Details zu jeder Seite. Diese Seitenobjekte enthalten nicht die Katalogblätter (Elemente). Die Reihenfolge der Elemente in diesem Array ist nicht definiert. Seiten können vom Client im Arbeitsspeicher mithilfe ihrer commitTimeStamp Eigenschaft sortiert werden.

Wenn neue Seiten eingeführt werden, werden die count Elemente erhöht, und neue Objekte werden im items Array angezeigt.

Wenn dem Katalog Elemente hinzugefügt werden, ändert sich der Index commitId und erhöht sich.commitTimeStamp Diese beiden Eigenschaften sind im Wesentlichen eine Zusammenfassung über alle Seiten commitId und commitTimeStamp Werte im items Array.

Katalogseitenobjekt im Index

Die Katalogseitenobjekte, die in der Eigenschaft des items Katalogindex gefunden werden, weisen die folgenden Eigenschaften auf:

Name Type Erforderlich Notizen
@id Zeichenfolge ja Die URL zum Abrufen der Katalogseite
commitId Zeichenfolge ja Eine eindeutige ID, die dem letzten Commit auf dieser Seite zugeordnet ist
commitTimeStamp Zeichenfolge ja Zeitstempel des letzten Commits auf dieser Seite
count integer ja Die Gesamtzahl der Elemente im Cache

Im Gegensatz zur Paketmetadatenressource , die in einigen Fällen Inlines in den Index verlässt, werden Katalogblätter nie in den Index eingebettet und müssen immer mithilfe der URL der Seite @id abgerufen werden.

Beispielanforderung

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

Beispiel für eine Antwort

{
  "commitId": "3d698852-eefb-48ed-8f55-9ee357540d20",
  "commitTimeStamp": "2017-10-31T23:33:17.0954363Z",
  "count": 3,
  "items": [
    {
      "@id": "https://api.nuget.org/v3/catalog0/page0.json",
      "commitId": "3a4df280-3d86-458e-a713-4c91ca261fef",
      "commitTimeStamp": "2015-02-01T06:30:11.7477681Z",
      "count": 540
    },
    {
      "@id": "https://api.nuget.org/v3/catalog0/page1.json",
      "commitId": "8bcd3cbf-74f0-47a2-a7ae-b7ecc50005d3",
      "commitTimeStamp": "2015-02-01T06:39:53.9553899Z",
      "count": 540
    },
    {
      "@id": "https://api.nuget.org/v3/catalog0/page2.json",
      "commitId": "3d698852-eefb-48ed-8f55-9ee357540d20",
      "commitTimeStamp": "2017-10-31T23:33:17.0954363Z",
      "count": 47
    }
  ]
}

Katalogseite

Die Katalogseite ist eine Sammlung von Katalogelementen. Es handelt sich um ein Dokument, das mithilfe eines der @id Werte im Katalogindex abgerufen wird. Die URL zu einer Katalogseite soll nicht vorhersehbar sein und sollte nur mit dem Katalogindex ermittelt werden.

Neue Katalogelemente werden der Seite im Katalogindex nur mit dem höchsten Commit-Zeitstempel oder einer neuen Seite hinzugefügt. Sobald eine Seite mit einem höheren Commit-Zeitstempel zum Katalog hinzugefügt wurde, werden ältere Seiten nie hinzugefügt oder geändert.

Das Katalogseitendokument ist ein JSON-Objekt mit den folgenden Eigenschaften:

Name Type Erforderlich Hinweise
commitId Zeichenfolge ja Eine eindeutige ID, die dem letzten Commit auf dieser Seite zugeordnet ist
commitTimeStamp Zeichenfolge ja Zeitstempel des letzten Commits auf dieser Seite
count integer ja Die Anzahl der Elemente auf der Seite
items Array von Objekten ja Die Katalogelemente auf dieser Seite
parent Zeichenfolge ja Eine URL zum Katalogindex

Jedes Element im items-Array ist ein Objekt mit minimalen Details zum Katalogelement. Diese Elementobjekte enthalten nicht alle Daten des Katalogelements. Die Reihenfolge der Elemente im Array der Seite items ist nicht definiert. Elemente können vom Client im Arbeitsspeicher mithilfe ihrer commitTimeStamp Eigenschaft sortiert werden.

Die Anzahl der Katalogelemente auf einer Seite wird durch die Serverimplementierung definiert. Für nuget.org gibt es höchstens 550 Elemente auf jeder Seite, obwohl die tatsächliche Anzahl für einige Seiten je nach Größe des nächsten Commitbatches zu dem Zeitpunkt kleiner sein kann.

Wenn neue Artikel eingeführt werden, wird das count inkrementiert und neue Katalogartikelobjekte erscheinen im Array items.

Wenn der Seite Elemente hinzugefügt werden, werden die commitId Änderungen und die commitTimeStamp Erhöhungen vorgenommen. Diese beiden Eigenschaften sind im Wesentlichen eine Zusammenfassung über alle commitId Werte commitTimeStamp im items Array.

Katalogelementobjekt auf einer Seite

Die Katalogelementobjekte, die in der Eigenschaft der Katalogseite items gefunden werden, weisen die folgenden Eigenschaften auf:

Name Type Erforderlich Notizen
@id Zeichenfolge ja Die URL zum Abrufen des Katalogelements
@type Zeichenfolge ja Der Typ der Katalogelements
commitId Zeichenfolge ja Die Commit-ID, die diesem Katalogelement zugeordnet ist
commitTimeStamp Zeichenfolge ja Der Commit-Zeitstempel dieses Katalogelements
nuget:id Zeichenfolge ja Die Paket-ID, mit der dieses Blatt verknüpft ist
nuget:version Zeichenfolge ja Die Paketversion, mit der dieses Blatt verknüpft ist

Der @type-Wert kann einer der folgenden Werte sein:

  1. nuget:PackageDetails: dies PackageDetails entspricht dem Typ im Katalogblattdokument.
  2. nuget:PackageDelete: dies entspricht dem PackageDelete Typ im Katalogblattdokument.

Weitere Informationen dazu, was jeder Typ bedeutet, finden Sie unten im entsprechenden Elementtyp.

Beispielanforderung

GET https://api.nuget.org/v3/catalog0/page2926.json

Beispiel für eine Antwort

{
  "commitId": "616117f5-d9dd-4664-82b9-74d87169bbe9",
  "commitTimeStamp": "2017-10-31T23:30:32.4197849Z",
  "count": 5,
  "parent": "https://api.nuget.org/v3/catalog0/index.json",
  "items": [
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.23.30.32/util.biz.payments.0.0.4-preview.json",
      "@type": "nuget:PackageDetails",
      "commitId": "616117f5-d9dd-4664-82b9-74d87169bbe9",
      "commitTimeStamp": "2017-10-31T23:30:32.4197849Z",
      "nuget:id": "Util.Biz.Payments",
      "nuget:version": "0.0.4-preview"
    },
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.23.28.02/util.biz.0.0.4-preview.json",
      "@type": "nuget:PackageDetails",
      "commitId": "820340b2-97e3-4f93-b82e-bc85550a6560",
      "commitTimeStamp": "2017-10-31T23:28:02.788239Z",
      "nuget:id": "Util.Biz",
      "nuget:version": "0.0.4-preview"
    },
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.22.31.22/sourcecode.clay.data.1.0.0-preview1-00258.json",
      "@type": "nuget:PackageDetails",
      "commitId": "cae34527-ffc7-4e96-884f-7cf95a32dbdd",
      "commitTimeStamp": "2017-10-31T22:31:22.5169519Z",
      "nuget:id": "SourceCode.Clay.Data",
      "nuget:version": "1.0.0-preview1-00258"
    },
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.22.31.22/sourcecode.clay.1.0.0-preview1-00258.json",
      "@type": "nuget:PackageDetails",
      "commitId": "cae34527-ffc7-4e96-884f-7cf95a32dbdd",
      "commitTimeStamp": "2017-10-31T22:31:22.5169519Z",
      "nuget:id": "SourceCode.Clay",
      "nuget:version": "1.0.0-preview1-00258"
    },
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.22.31.22/sourcecode.clay.json.1.0.0-preview1-00258.json",
      "@type": "nuget:PackageDetails",
      "commitId": "cae34527-ffc7-4e96-884f-7cf95a32dbdd",
      "commitTimeStamp": "2017-10-31T22:31:22.5169519Z",
      "nuget:id": "SourceCode.Clay.Json",
      "nuget:version": "1.0.0-preview1-00258"
    }
  ]
}

Katalogblatt

Das Katalogblatt enthält Metadaten zu einer bestimmten Paket-ID und -Version zu einem bestimmten Zeitpunkt. Es handelt sich um ein Dokument, das mithilfe des @id In einer Katalogseite gefundenen Werts abgerufen wird. Die URL zu einem Katalogblatt soll nicht vorhersehbar sein und sollte nur mithilfe einer Katalogseite ermittelt werden.

Das Katalogblattdokument ist ein JSON-Objekt mit den folgenden Eigenschaften:

Name Type Erforderlich Hinweise
@type Zeichenfolge oder Array von Zeichenfolgen ja Der Typ des Katalogelement
catalog:commitId Zeichenfolge ja Eine Commit-ID, die diesem Katalogelement zugeordnet ist
catalog:commitTimeStamp Zeichenfolge ja Der Commit-Zeitstempel dieses Katalogelements
id string ja Der Pfad des Katalogelements
published Zeichenfolge ja Das Veröffentlichungsdatum des Paketkatalogelements
version Zeichenfolge ja Die Paketversion der Katalogposition

Elementtypen

Die @type Eigenschaft ist eine Zeichenfolge oder eine Zeichenfolgenmatrix Wenn es sich bei dem @type Wert um eine Zeichenfolge handelt, sollte der Wert als beliebiges Array von Größe 1 behandelt werden. Nicht alle möglichen Werte sind @type dokumentiert. Jedes Katalogelement weist jedoch genau einen der beiden folgenden Zeichenfolgentypwerte auf:

  1. PackageDetails: stellt eine Momentaufnahme von Paketmetadaten dar
  2. PackageDelete: stellt ein Paket dar, das gelöscht wurde

Katalogelemente des Paketdetails

Katalogelemente mit dem Typ PackageDetails enthalten eine Momentaufnahme von Paketmetadaten für ein bestimmtes Paket (ID und Versionskombination). Ein Paketdetails-Katalogelement wird erstellt, wenn eine Paketquelle auf eines der folgenden Szenarien trifft:

  1. Ein Paket wird pushed.
  2. Ein Paket wird erneut aufgelistet.
  3. Ein Paket ist nicht aufgelistet.
  4. Ein Paket ist veraltet.
  5. Ein Paket ist nicht erkannt.
  6. Ein Paket wird umgebrochen.
  7. Der Sicherheitsrisikostatus eines Pakets wird aktualisiert.

Ein Paketumbruch ist eine administrative Geste, die im Wesentlichen einen gefälschten Push eines vorhandenen Pakets ohne Änderungen an dem Paket selbst generiert. Bei nuget.org wird ein Umbruch verwendet, nachdem ein Fehler in einem der Hintergrundaufträge behoben wurde, die den Katalog verbrauchen.

Clients, die die Katalogelemente verwenden, sollten nicht versuchen, zu bestimmen, welche dieser Szenarien das Katalogelement erzeugt hat. Stattdessen sollte der Client einfach alle Standard tained view or index with the metadata contained in the catalog item aktualisieren. Darüber hinaus sollten doppelte oder redundante Katalogelemente ordnungsgemäß behandelt werden (idempotently).

Die Katalogpositionen der Paketdetails haben zusätzlich zu den Eigenschaften aller Katalogblätter die folgenden Eigenschaften.

Name Type Erforderlich Hinweise
authors Zeichenfolge Nein
erstellt Zeichenfolge Nein Ein Zeitstempel, zu dem das Paket zum ersten Mal erstellt wurde. Fallback-Eigenschaft: published.
Abhängigkeitsgruppen Array von Objekten Nein Die Abhängigkeiten des Pakets, gruppiert nach Zielframework (gleiches Format wie die Paketmetadatenressource)
Verwerfung Objekt Nein Die dem Paket zugeordnete Verwerfung (gleiches Format wie die Paket-Metadaten-Ressource)
Beschreibung string Nein
iconUrl Zeichenfolge Nein
isPrerelease boolean Nein Gibt an, ob die Paketversion vorab verfügbar ist. Kann erkannt werden von version.
language Zeichenfolge Nein
licenseUrl Zeichenfolge Nein
aufgeführt. boolean Nein Gibt an, ob das Paket aufgelistet ist
minClientVersion Zeichenfolge Nein
packageHash Zeichenfolge ja Der Hash des Pakets, Codierung mit Standard base64
packageHashAlgorithm Zeichenfolge ja
packageSize integer ja PackageSize Die Größe des Pakets in Bytes
packageTypes Array von Objekten Nein Die vom Autor angegebenen Pakettypen.
projectUrl Zeichenfolge Nein
releaseNotes Zeichenfolge Nein
requireLicenseAgreement boolean Nein Angenommen false, wenn ausgeschlossen
Zusammenfassung Zeichenfolge Nein
Tags Zeichenfolgenarray Nein
title string Nein
verbatimVersion Zeichenfolge Nein Die Versionszeichenfolge, wie sie ursprünglich in der NUSPEC gefunden wurde
vulnerabilities Array von Objekten Nein Die Sicherheitsrisiken des Pakets

Die Paketeigenschaft version ist die Vollversionszeichenfolge nach der Normalisierung. Dies bedeutet, dass Hier SemVer 2.0.0 Builddaten enthalten sein können.

Der Zeitstempel created ist der Zeitpunkt, an dem das Paket zum ersten Mal von der Paketquelle empfangen wurde, was in der Regel kurz vor dem Zeitstempel der Übergabe des Katalogobjekts liegt.

Dies packageHashAlgorithm ist eine Zeichenfolge, die von der Serverimplementierung definiert wird, die den Hashalgorithmus darstellt, der verwendet wird, um die packageHash. nuget.org immer den packageHashAlgorithm Wert von SHA512.

Die packageTypes Eigenschaft ist nur vorhanden, wenn vom Autor ein Pakettyp angegeben wurde. Wenn sie vorhanden ist, hat sie immer mindestens einen (1) Eintrag. Jeder Artikel im Array packageTypes ist ein JSON-Objekt mit den folgenden Eigenschaften:

Name Type Erforderlich Hinweise
name Zeichenfolge ja Der Name des Pakettyps.
version Zeichenfolge Nein Die Version des Pakettyps. Nur vorhanden, wenn der Autor explizit eine Version in der Nuspec angegeben hat.

Der published Zeitstempel ist der Zeitpunkt, zu dem das Paket zuletzt aufgeführt wurde.

Hinweis

Bei nuget.org wird der published Wert auf das Jahr 1900 festgelegt, wenn das Paket nicht aufgelistet ist.

Sicherheitsrisiken

Ein Array von vulnerability-Objekten. Jede Suche bietet folgende Eigenschaften:

Name Type Erforderlich Hinweise
advisoryUrl Zeichenfolge ja Standort der Sicherheitsempfehlung für das Paket
severity Zeichenfolge ja Schweregrad der Empfehlung: "0" = Niedrig, "1" = Mittel, "2" = Hoch, "3" = Kritisch

Wenn die severity Eigenschaft andere Werte als die hier aufgeführten enthält, ist der Schweregrad der Empfehlung als niedrig zu behandeln.

Beispielanforderung

GET https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json

Beispiel für eine Antwort

{
  "@type": [
    "PackageDetails",
    "catalog:Permalink"
  ],
  "authors": "NuGet.org Team",
  "catalog:commitId": "49fe04d8-5694-45a5-9822-3be61bda871b",
  "catalog:commitTimeStamp": "2015-02-01T11:18:40.8589193Z",
  "created": "2011-12-02T20:21:23.74Z",
  "description": "This package is an example for the V3 protocol.",
  "deprecation": {
    "reasons": [
      "Legacy",
      "HasCriticalBugs",
      "Other"
    ],
    "message": "This package is an example--it should not be used!",
    "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",
  "isPrerelease": false,
  "language": "en-US",
  "licenseUrl": "http://www.opensource.org/licenses/ms-pl",
  "packageHash": "2edCwKLcbcgFJpsAwa883BLtOy8bZpWwbQpiIb71E74k5t2f2WzXEGWbPwntRleUEgSrcxJrh9Orm/TAmgO4NQ==",
  "packageHashAlgorithm": "SHA512",
  "packageSize": 118348,
  "packageTypes": [
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#packagetypes/DotnetTool",
      "@type": "PackageType",
      "name": "DotnetTool"
    }
  ],
  "projectUrl": "https://github.com/NuGet/NuGetGallery",
  "published": "1900-01-01T00:00:00Z",
  "requireLicenseAcceptance": false,
  "title": "NuGet V3 Protocol Example",
  "version": "1.0.0",
  "dependencyGroups": [
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup",
      "@type": "PackageDependencyGroup",
      "dependencies": [
        {
          "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup/aspnet.suppressformsredirect",
          "@type": "PackageDependency",
          "id": "aspnet.suppressformsredirect",
          "range": "[0.0.1.4, )"
        },
        {
          "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup/webactivator",
          "@type": "PackageDependency",
          "id": "WebActivator",
          "range": "[1.4.4, )"
        },
        {
          "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup/webapi.all",
          "@type": "PackageDependency",
          "id": "WebApi.All",
          "range": "[0.5.0, )"
        }
      ],
      "targetFramework": ".NETFramework4.6"
    }
  ],
  "tags": [
    "NuGet",
    "V3",
    "Protocol",
    "Example"
  ],
  "vulnerabilities": [
    {
      "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#vulnerability/GitHub/999",
      "@type": "Vulnerability",
      "advisoryUrl": "https://github.com/advisories/ABCD-1234-5678-9012",
      "severity": "2"
    }
  ]
}

Paketlöschkatalogelemente

Katalogelemente mit dem Typ PackageDelete enthalten einen minimalen Satz von Informationen, die für Katalogclients angeben, dass ein Paket aus der Paketquelle gelöscht wurde und für einen Paketvorgang (z. B. Wiederherstellen) nicht mehr verfügbar ist.

Hinweis

Es ist möglich, dass ein Paket gelöscht und später mit derselben Paket-ID und -Version erneut veröffentlicht wird. Bei nuget.org ist dies ein sehr seltener Fall, da es die Annahme des offiziellen Kunden unterbricht, dass eine Paket-ID und -Version einen bestimmten Paketinhalt impliziert. Weitere Informationen zum Löschen von Paketen auf nuget.org finden Sie in unserer Richtlinie.

Katalogobjekte zum Löschen von Paketen haben keine zusätzlichen Eigenschaften, die über die Eigenschaften aller Katalogblätter hinausgehen.

Die version Eigenschaft ist die ursprüngliche Versionszeichenfolge, die im Paket ".nuspec" gefunden wurde.

Die Eigenschaft published ist der Zeitpunkt, an dem das Paket gelöscht wurde, was normalerweise kurz vor dem Zeitstempel der Übergabe des Katalogobjekts liegt.

Beispielanforderung

GET https://api.nuget.org/v3/catalog0/data/2017.11.02.00.40.00/netstandard1.4_lib.1.0.0-test.json

Beispiel für eine Antwort

{
  "@type": [
    "PackageDelete",
    "catalog:Permalink"
  ],
  "catalog:commitId": "19fec5b4-9335-4e4b-bd50-8d5d3f734597",
  "catalog:commitTimeStamp": "2017-11-02T00:40:00.1969812Z",
  "id": "netstandard1.4_lib",
  "originalId": "netstandard1.4_lib",
  "published": "2017-11-02T00:37:43.7181952Z",
  "version": "1.0.0-test"
}

Cursor

Übersicht

In diesem Abschnitt wird ein Clientkonzept beschrieben, das zwar nicht unbedingt durch das Protokoll vorgeschrieben ist, teil einer praktischen Katalogclientimplementierung sein sollte.

Da es sich bei dem Katalog um eine nur anhängende Datenstruktur handelt, die durch die Zeit indiziert ist, sollte der Client einen Cursor lokal speichern, der angibt, bis zu welchem Zeitpunkt der Client Katalogelemente verarbeitet hat. Beachten Sie, dass dieser Cursorwert niemals mithilfe der Computeruhr des Clients generiert werden sollte. Stattdessen sollte der Wert aus dem Wert eines Katalogobjekts commitTimestamp stammen.

Jedes Mal, wenn der Client neue Ereignisse in der Paketquelle verarbeiten möchte, muss er nur den Katalog für alle Katalogelemente mit einem Commit-Zeitstempel abfragen, der größer als der gespeicherte Cursor ist. Nachdem der Client alle neuen Katalogelemente erfolgreich verarbeitet hat, zeichnet er den neuesten Commit-Zeitstempel von Katalogelementen auf, die gerade als neuer Cursorwert verarbeitet wurden.

Mit diesem Ansatz kann der Client sicher sein, dass keine Paketereignisse fehlen, die in der Paketquelle aufgetreten sind. Darüber hinaus muss der Client keine alten Ereignisse vor dem aufgezeichneten Commit-Zeitstempel des Cursors erneut verarbeiten.

Dieses leistungsstarke Konzept von Cursorn wird für viele nuget.org Hintergrundaufträge verwendet und wird verwendet, um die V3-API selbst auf dem neuesten Stand zu halten.

Anfangswert

Wenn der Katalogclient zum ersten Mal gestartet wird (und daher keinen Cursorwert aufweist), sollte er einen Standardcursorwert verwenden. Nets System.DateTimeOffset.MinValue oder ein solcher analoger Begriff des minimalen, darstellbaren Zeitstempels.

Durchlaufen von Katalogelementen

Um den nächsten zu verarbeitenden Katalogelementesatz abzufragen, sollte der Client Folgendes ausführen:

  1. Rufen Sie den aufgezeichneten Cursorwert aus einem lokalen Speicher ab.
  2. Laden Sie den Katalogindex herunter und deserialisieren Sie ihn.
  3. Suchen Sie alle Katalogseiten mit einem Commit-Zeitstempel , der größer als der Cursor ist .
  4. Deklarieren Sie eine leere Liste der zu verarbeitenden Katalogelemente.
  5. Für jede Katalogseite, die in Schritt 3 übereinstimmt:
    1. Laden Sie die Katalogseite herunter und deserialisieren Sie sie.
    2. Suche nach allen Katalogeinträgen mit einem Zeitstempel, der größer ist als der des Cursors.
    3. Fügen Sie alle übereinstimmenden Katalogpositionen zu der in Schritt 4 angegebenen Liste hinzu.
  6. Sortieren Sie die Katalogelementliste nach Commit-Zeitstempel.
  7. Verarbeiten Sie jedes Katalogelement in Sequenz:
    1. Laden Sie das Katalogelement herunter und deserialisieren Sie es.
    2. Reagieren Sie entsprechend auf den Typ des Katalogelements.
    3. Verarbeiten des Katalogelementdokuments in clientspezifischer Weise.
  8. Notieren Sie den Commit-Zeitstempel des letzten Katalogelements als neuen Cursorwert.

Mit diesem grundlegenden Algorithmus kann die Clientimplementierung eine vollständige Ansicht aller Pakete erstellen, die in der Paketquelle verfügbar sind. Der Client muss diesen Algorithmus nur in regelmäßigen Abständen ausführen, um immer die neuesten Änderungen an der Paketquelle zu beachten.

Hinweis

Dies ist der Algorithmus, der nuget.org verwendet, um die Ressourcen "Paketmetadaten", "Paketinhalt", "Suche" und "AutoVervollständigen" auf dem neuesten Stand zu halten.

Abhängige Cursor

Angenommen, es gibt zwei Katalogclients, die eine inhärente Abhängigkeit aufweisen, wobei die Ausgabe eines Clients von der Ausgabe eines anderen Clients abhängt.

Beispiel

Beispielsweise sollte bei nuget.org ein neu veröffentlichtes Paket nicht in der Suchressource angezeigt werden, bevor es in der Paketmetadatenressource angezeigt wird. Dies liegt daran, dass der vom offiziellen NuGet-Client ausgeführte Vorgang "Wiederherstellen" die Paketmetadatenressource verwendet. Wenn ein Kunde ein Paket mithilfe des Suchdiensts ermittelt, sollte er in der Lage sein, dieses Paket mithilfe der Paketmetadatenressource erfolgreich wiederherzustellen. Mit anderen Worten, die Suchressource hängt von der Paket-Metadaten-Ressource ab. Jede Ressource verfügt über einen Katalogclient-Hintergrundauftrag, der diese Ressource aktualisiert. Jeder Client verfügt über einen eigenen Cursor.

Da beide Ressourcen aus dem Katalog aufgebaut sind, darf der Cursor des Katalogclients, der die Suchressource aktualisiert, nicht über den Cursor des Paketmetadatenkatalogclients hinausgehen.

Algorithmus

Um diese Einschränkung zu implementieren, ändern Sie einfach den obigen Algorithmus so, dass er lautet:

  1. Rufen Sie den aufgezeichneten Cursorwert aus einem lokalen Speicher ab.
  2. Laden Sie den Katalogindex herunter und deserialisieren Sie ihn.
  3. Suchen Sie alle Katalogseiten mit einem Commit-Zeitstempel , der größer als der Cursor kleiner oder gleich dem Cursor der Abhängigkeit ist.
  4. Deklarieren Sie eine leere Liste der zu verarbeitenden Katalogelemente.
  5. Für jede Katalogseite, die in Schritt 3 übereinstimmt:
    1. Laden Sie die Katalogseite herunter und deserialisieren Sie sie.
    2. Suche nach allen Katalogeinträgen mit einem Commit-Zeitstempel größer als der Cursor kleiner oder gleich dem Cursor der Abhängigkeit.
    3. Fügen Sie alle übereinstimmenden Katalogpositionen zu der in Schritt 4 angegebenen Liste hinzu.
  6. Sortieren Sie die Katalogelementliste nach Commit-Zeitstempel.
  7. Verarbeiten Sie jedes Katalogelement in Sequenz:
    1. Laden Sie das Katalogelement herunter und deserialisieren Sie es.
    2. Reagieren Sie entsprechend auf den Typ des Katalogelements.
    3. Verarbeiten des Katalogelementdokuments in clientspezifischer Weise.
  8. Notieren Sie den Commit-Zeitstempel des letzten Katalogelements als neuen Cursorwert.

Mit diesem geänderten Algorithmus können Sie ein System abhängiger Katalogclients erstellen, das alle ihre eigenen spezifischen Indizes, Artefakte usw. erzeugen.