Katalog
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:
nuget:PackageDetails: diesPackageDetailsentspricht dem Typ im Katalogblattdokument.nuget:PackageDelete: dies entspricht demPackageDeleteTyp 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:
PackageDetails: stellt eine Momentaufnahme von Paketmetadaten darPackageDelete: 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:
- Ein Paket wird pushed.
- Ein Paket wird erneut aufgelistet.
- Ein Paket ist nicht aufgelistet.
- Ein Paket ist veraltet.
- Ein Paket ist nicht erkannt.
- Ein Paket wird umgebrochen.
- 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:
- Rufen Sie den aufgezeichneten Cursorwert aus einem lokalen Speicher ab.
- Laden Sie den Katalogindex herunter und deserialisieren Sie ihn.
- Suchen Sie alle Katalogseiten mit einem Commit-Zeitstempel , der größer als der Cursor ist .
- Deklarieren Sie eine leere Liste der zu verarbeitenden Katalogelemente.
- Für jede Katalogseite, die in Schritt 3 übereinstimmt:
- Laden Sie die Katalogseite herunter und deserialisieren Sie sie.
- Suche nach allen Katalogeinträgen mit einem Zeitstempel, der größer ist als der des Cursors.
- Fügen Sie alle übereinstimmenden Katalogpositionen zu der in Schritt 4 angegebenen Liste hinzu.
- Sortieren Sie die Katalogelementliste nach Commit-Zeitstempel.
- Verarbeiten Sie jedes Katalogelement in Sequenz:
- Laden Sie das Katalogelement herunter und deserialisieren Sie es.
- Reagieren Sie entsprechend auf den Typ des Katalogelements.
- Verarbeiten des Katalogelementdokuments in clientspezifischer Weise.
- 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:
- Rufen Sie den aufgezeichneten Cursorwert aus einem lokalen Speicher ab.
- Laden Sie den Katalogindex herunter und deserialisieren Sie ihn.
- Suchen Sie alle Katalogseiten mit einem Commit-Zeitstempel , der größer als der Cursor kleiner oder gleich dem Cursor der Abhängigkeit ist.
- Deklarieren Sie eine leere Liste der zu verarbeitenden Katalogelemente.
- Für jede Katalogseite, die in Schritt 3 übereinstimmt:
- Laden Sie die Katalogseite herunter und deserialisieren Sie sie.
- Suche nach allen Katalogeinträgen mit einem Commit-Zeitstempel größer als der Cursor kleiner oder gleich dem Cursor der Abhängigkeit.
- Fügen Sie alle übereinstimmenden Katalogpositionen zu der in Schritt 4 angegebenen Liste hinzu.
- Sortieren Sie die Katalogelementliste nach Commit-Zeitstempel.
- Verarbeiten Sie jedes Katalogelement in Sequenz:
- Laden Sie das Katalogelement herunter und deserialisieren Sie es.
- Reagieren Sie entsprechend auf den Typ des Katalogelements.
- Verarbeiten des Katalogelementdokuments in clientspezifischer Weise.
- 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.
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für