Catalogo
Il catalogo è una risorsa che registra tutte le operazioni sui pacchetti in un'origine del pacchetto, ad esempio creazioni ed eliminazioni. La risorsa del catalogo ha il Catalog tipo nell'indice del servizio. È possibile usare questa risorsa per eseguire query per tutti i pacchetti pubblicati.
Nota
Poiché il catalogo non viene usato dal client NuGet ufficiale, non tutte le origini dei pacchetti implementano il catalogo.
Nota
Attualmente, il catalogo nuget.org non è disponibile in Cina. Per altre informazioni, vedere NuGet/NuGetGallery#4949.
Controllo delle versioni
Viene usato il valore seguente @type :
| Valore @type | Note |
|---|---|
| Catalogo/3.0.0 | Versione iniziale |
URL di base
L'URL del punto di ingresso per le API seguenti è il valore della @id proprietà associata ai valori di risorsa indicati in precedenza @type . In questo argomento viene usato l'URL {@id}segnaposto .
Metodi HTTP
Tutti gli URL trovati nella risorsa del catalogo supportano solo i metodi GET HTTP e HEAD.
Indice del catalogo
L'indice del catalogo è un documento in una posizione nota con un elenco di elementi del catalogo, ordinati cronologicamente. Si tratta del punto di ingresso della risorsa del catalogo.
L'indice è costituito da pagine del catalogo. Ogni pagina del catalogo contiene elementi del catalogo. Ogni elemento del catalogo rappresenta un evento relativo a un singolo pacchetto in un momento specifico. Un elemento del catalogo può rappresentare un pacchetto creato, non elencato, elencato o eliminato dall'origine del pacchetto. Elaborando gli elementi del catalogo in ordine cronologico, il client può creare una visualizzazione aggiornata di ogni pacchetto presente nell'origine del pacchetto V3.
In breve, i BLOB di catalogo hanno la struttura gerarchica seguente:
- Indice: punto di ingresso per il catalogo.
- Pagina: raggruppamento di elementi del catalogo.
- Foglia: documento che rappresenta un elemento del catalogo, ovvero uno snapshot dello stato di un singolo pacchetto.
Ogni oggetto catalogo ha una proprietà denominata che commitTimeStamp rappresenta quando l'elemento è stato aggiunto al catalogo. Gli elementi del catalogo vengono aggiunti a una pagina del catalogo in batch denominati commit. Tutti gli elementi del catalogo nello stesso commit hanno lo stesso timestamp di commit (commitTimeStamp) e l'ID commit (commitId). Gli elementi del catalogo inseriti nello stesso commit rappresentano eventi che si sono verificati nello stesso momento nell'origine del pacchetto. Non esiste alcun ordinamento all'interno di un commit del catalogo.
Poiché ogni ID pacchetto e versione è univoco, non ci sarà mai più di un elemento del catalogo in un commit. Ciò garantisce che gli elementi del catalogo per un singolo pacchetto possano sempre essere ordinati in modo non ambiguo rispetto al timestamp di commit.
Non è mai presente più di un commit nel catalogo per commitTimeStamp. In altre parole, è commitId ridondante con .commitTimeStamp
A differenza della risorsa di metadati del pacchetto, indicizzata in base all'ID del pacchetto, il catalogo viene indicizzato (e su cui è possibile eseguire query) solo per volta.
Gli elementi del catalogo vengono sempre aggiunti al catalogo in un ordine cronologico che aumenta in modo monotonico. Ciò significa che se al momento X viene aggiunto un commit del catalogo, non verrà mai aggiunto alcun commit del catalogo con un tempo minore o uguale a X.
La richiesta seguente recupera l'indice del catalogo.
GET {@id}
L'indice del catalogo è un documento JSON che contiene un oggetto con le proprietà seguenti:
| Nome | Digita | Obbligatorio | Note |
|---|---|---|---|
| commitId | string | yes | ID univoco associato al commit più recente |
| commitTimeStamp | string | yes | Timestamp del commit più recente |
| numero | integer | yes | Numero di pagine nell'indice |
| articoli | matrice di oggetti | yes | Matrice di oggetti, ogni oggetto che rappresenta una pagina |
Ogni elemento della items matrice è un oggetto con alcuni dettagli minimi su ogni pagina. Questi oggetti pagina non contengono le foglie del catalogo (elementi). L'ordine degli elementi in questa matrice non è definito. Le pagine possono essere ordinate dal client in memoria usando la relativa commitTimeStamp proprietà .
Man mano che vengono introdotte nuove pagine, l'oggetto count verrà incrementato e i nuovi oggetti verranno visualizzati nella items matrice.
Man mano che gli elementi vengono aggiunti al catalogo, l'indice commitId cambierà e aumenterà commitTimeStamp . Queste due proprietà sono essenzialmente un riepilogo su tutte le pagine commitId e commitTimeStamp i valori nella items matrice.
Oggetto pagina catalogo nell'indice
Gli oggetti pagina del catalogo trovati nella proprietà dell'indice del items catalogo hanno le proprietà seguenti:
| Nome | Digita | Obbligatorio | Note |
|---|---|---|---|
| @id | string | yes | URL da recuperare la pagina del catalogo |
| commitId | string | yes | ID univoco associato al commit più recente in questa pagina |
| commitTimeStamp | string | yes | Timestamp del commit più recente in questa pagina |
| numero | integer | yes | Numero di elementi nella pagina del catalogo |
A differenza della risorsa di metadati del pacchetto che in alcuni casi lascia inline nell'indice, le foglie del catalogo non vengono mai inlinedi nell'indice e devono sempre essere recuperate usando l'URL della @id pagina.
Esempio di richiesta
GET https://api.nuget.org/v3/catalog0/index.json
Risposta di esempio
{
"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
}
]
}
Pagina Catalogo
La pagina del catalogo è una raccolta di elementi del catalogo. Si tratta di un documento recuperato utilizzando uno dei @id valori trovati nell'indice del catalogo. L'URL di una pagina del catalogo non deve essere prevedibile e deve essere individuato usando solo l'indice del catalogo.
I nuovi elementi del catalogo vengono aggiunti alla pagina nell'indice del catalogo solo con il timestamp di commit più alto o in una nuova pagina. Dopo l'aggiunta di una pagina con un timestamp di commit superiore al catalogo, le pagine precedenti non vengono mai aggiunte o modificate.
Il documento della pagina del catalogo è un oggetto JSON con le proprietà seguenti:
| Nome | Digita | Obbligatorio | Note |
|---|---|---|---|
| commitId | string | yes | ID univoco associato al commit più recente in questa pagina |
| commitTimeStamp | string | yes | Timestamp del commit più recente in questa pagina |
| numero | integer | yes | Numero di elementi nella pagina |
| articoli | matrice di oggetti | yes | Elementi del catalogo in questa pagina |
| parent | string | yes | URL dell'indice del catalogo |
Ogni elemento della items matrice è un oggetto con alcuni dettagli minimi sull'elemento del catalogo. Questi oggetti elemento non contengono tutti i dati dell'elemento del catalogo. L'ordine degli elementi nella matrice della items pagina non è definito. Gli elementi possono essere ordinati dal client in memoria usando la relativa commitTimeStamp proprietà .
Il numero di elementi del catalogo in una pagina è definito dall'implementazione del server. Per nuget.org, in ogni pagina sono presenti al massimo 550 elementi, anche se il numero effettivo può essere inferiore per alcune pagine a seconda delle dimensioni del batch di commit successivo nel momento in cui si trova.
Man mano che vengono introdotti nuovi elementi, l'oggetto count viene incrementato e i nuovi oggetti elemento del items catalogo vengono visualizzati nella matrice.
Man mano che gli elementi vengono aggiunti alla pagina, le commitId modifiche e gli commitTimeStamp aumenti. Queste due proprietà sono essenzialmente un riepilogo su tutti i commitId valori e commitTimeStamp nella items matrice.
Oggetto elemento catalogo in una pagina
Gli oggetti elemento del catalogo trovati nella proprietà della pagina del items catalogo hanno le proprietà seguenti:
| Nome | Digita | Obbligatorio | Note |
|---|---|---|---|
| @id | string | yes | URL per recuperare l'elemento del catalogo |
| @type | string | yes | Tipo dell'elemento del catalogo |
| commitId | string | yes | ID commit associato a questo elemento del catalogo |
| commitTimeStamp | string | yes | Timestamp di commit dell'elemento del catalogo |
| nuget:id | string | yes | ID pacchetto a cui è correlata questa foglia |
| nuget:version | string | yes | Versione del pacchetto correlata a questa foglia |
Il @type valore sarà uno dei due valori seguenti:
nuget:PackageDetails: corrisponde alPackageDetailstipo nel documento foglia del catalogo.nuget:PackageDelete: corrisponde alPackageDeletetipo nel documento foglia del catalogo.
Per altre informazioni sul significato di ogni tipo, vedere il tipo di elementi corrispondente di seguito.
Esempio di richiesta
GET https://api.nuget.org/v3/catalog0/page2926.json
Risposta di esempio
{
"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"
}
]
}
Foglia catalogo
La foglia del catalogo contiene metadati relativi a un ID pacchetto e una versione specifici in un determinato momento. Si tratta di un documento recuperato usando il @id valore trovato in una pagina del catalogo. L'URL di una foglia del catalogo non deve essere prevedibile e deve essere individuato usando solo una pagina del catalogo.
Il documento foglia del catalogo è un oggetto JSON con le proprietà seguenti:
| Nome | Digita | Obbligatorio | Note |
|---|---|---|---|
| @type | Stringa o matrice di stringhe | yes | Tipi dell'elemento del catalogo |
| catalog:commitId | string | yes | ID commit associato a questo elemento del catalogo |
| catalog:commitTimeStamp | string | yes | Timestamp di commit dell'elemento del catalogo |
| id | string | yes | ID pacchetto dell'elemento del catalogo |
| published | string | yes | Data di pubblicazione dell'elemento del catalogo pacchetti |
| versione | string | yes | Versione del pacchetto dell'elemento del catalogo |
Tipi di elemento
La @type proprietà è una stringa o una matrice di stringhe. Per praticità, se il @type valore è una stringa, deve essere considerato come qualsiasi matrice di dimensioni 1. Non tutti i valori possibili per @type sono documentati. Tuttavia, ogni elemento del catalogo ha esattamente uno dei due valori di tipo stringa seguenti:
PackageDetails: rappresenta uno snapshot dei metadati del pacchettoPackageDelete: rappresenta un pacchetto eliminato
Elementi del catalogo dei dettagli del pacchetto
Gli elementi del catalogo con il tipo PackageDetails contengono uno snapshot dei metadati del pacchetto per un pacchetto specifico (combinazione di ID e versione). Un elemento del catalogo dei dettagli del pacchetto viene generato quando un'origine del pacchetto rileva uno degli scenari seguenti:
- Viene eseguito il push di un pacchetto.
- Viene elencato di nuovo un pacchetto.
- Un pacchetto non è elencato.
- Un pacchetto è deprecato.
- Un pacchetto non è stato individuato.
- Viene eseguito il reflow di un pacchetto.
- Lo stato di vulnerabilità di un pacchetto viene aggiornato.
Un reflow del pacchetto è un gesto amministrativo che essenzialmente genera un push falso di un pacchetto esistente senza modifiche al pacchetto stesso. In nuget.org viene usato un reflow dopo la correzione di un bug in uno dei processi in background che utilizzano il catalogo.
I client che utilizzano gli elementi del catalogo non devono tentare di determinare quale di questi scenari ha prodotto l'elemento del catalogo. Al contrario, il client deve semplicemente aggiornare qualsiasi vista o indice gestito con i metadati contenuti nell'elemento del catalogo. Inoltre, gli elementi del catalogo duplicati o ridondanti devono essere gestiti normalmente (in modo idempotente).
Gli elementi del catalogo dei dettagli del pacchetto hanno le proprietà seguenti oltre a quelle incluse in tutte le foglie del catalogo.
| Nome | Digita | Obbligatorio | Note |
|---|---|---|---|
| authors | string | no | |
| created | string | no | Timestamp di quando il pacchetto è stato creato per la prima volta. Proprietà di fallback: published. |
| dependencyGroups | matrice di oggetti | no | Dipendenze del pacchetto, raggruppate per framework di destinazione (stesso formato della risorsa dei metadati del pacchetto) |
| Disapprovazione | object | no | Deprecazione associata al pacchetto (stesso formato della risorsa dei metadati del pacchetto) |
| description | stringa | no | |
| iconUrl | string | no | |
| isPrerelease | boolean | no | Indica se la versione del pacchetto è in versione non definitiva. È possibile rilevare da version. |
| lingua | string | no | |
| licenseUrl | string | no | |
| disponibili | boolean | no | Indica se il pacchetto è elencato o meno |
| minClientVersion | string | no | |
| packageHash | string | yes | Hash del pacchetto, codifica con base 64 standard |
| packageHashAlgorithm | string | yes | |
| packageSize | integer | yes | Dimensioni del pacchetto con estensione nupkg in byte |
| packageTypes | matrice di oggetti | no | Tipi di pacchetto specificati dall'autore. |
| projectUrl | string | no | |
| releaseNotes | string | no | |
| requireLicenseAgreement | boolean | no | Si supponga false se escluso |
| riepilogo | string | no | |
| tag | matrice di stringhe | no | |
| title | string | no | |
| verbatimVersion | string | no | Stringa di versione come originariamente trovato in .nuspec |
| vulnerabilità | matrice di oggetti | no | Vulnerabilità di sicurezza del pacchetto |
La proprietà del pacchetto version è la stringa di versione completa dopo la normalizzazione. Ciò significa che i dati di compilazione semVer 2.0.0 possono essere inclusi qui.
Il created timestamp è quando il pacchetto è stato ricevuto per la prima volta dall'origine del pacchetto, che in genere è poco tempo prima del timestamp di commit dell'elemento del catalogo.
packageHashAlgorithm è una stringa definita dall'implementazione del server che rappresenta l'algoritmo hash utilizzato per produrre l'oggetto packageHash. nuget.org sempre usato il packageHashAlgorithm valore di SHA512.
La packageTypes proprietà sarà presente solo se un tipo di pacchetto è stato specificato dall'autore. Se presente, avrà sempre almeno una voce (1). Ogni elemento nella packageTypes matrice è un oggetto JSON con le proprietà seguenti:
| Nome | Digita | Obbligatorio | Note |
|---|---|---|---|
| name | string | yes | Nome del tipo di pacchetto. |
| versione | string | no | Versione del tipo di pacchetto. Presente solo se l'autore ha specificato in modo esplicito una versione in nuspec. |
Il published timestamp è l'ora dell'ultimo elenco del pacchetto.
Nota
In nuget.org, il published valore viene impostato sull'anno 1900 quando il pacchetto non è elencato.
Vulnerabilità
Matrice di oggetti vulnerability. Ogni vulnerabilità ha le proprietà seguenti:
| Nome | Digita | Obbligatorio | Note |
|---|---|---|---|
| advisoryUrl | string | yes | Posizione dell'avviso di sicurezza per il pacchetto |
| severity | string | yes | Gravità dell'avviso: "0" = Basso, "1" = Moderato, "2" = Alto, "3" = Critico |
Se la severity proprietà contiene valori diversi da quelli elencati qui, la gravità dell'avviso deve essere considerata bassa.
Esempio di richiesta
GET https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json
Risposta di esempio
{
"@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"
}
]
}
Eliminazione pacchetti di elementi del catalogo
Gli elementi del catalogo con il tipo PackageDelete contengono un set minimo di informazioni che indicano ai client di catalogo che un pacchetto è stato eliminato dall'origine del pacchetto e non è più disponibile per qualsiasi operazione del pacchetto, ad esempio il ripristino.
Nota
È possibile eliminare un pacchetto e ripubblicare in un secondo momento usando lo stesso ID pacchetto e la stessa versione. In nuget.org, si tratta di un caso molto raro perché interrompe il presupposto del client ufficiale che un ID pacchetto e una versione implicano un contenuto specifico del pacchetto. Per altre informazioni sull'eliminazione dei pacchetti in nuget.org, vedere i criteri.
Gli elementi del catalogo di eliminazione del pacchetto non hanno proprietà aggiuntive oltre a quelle incluse in tutte le foglie del catalogo.
La version proprietà è la stringa di versione originale trovata nel pacchetto .nuspec.
La published proprietà è l'ora in cui il pacchetto è stato eliminato, in genere poco tempo prima del timestamp di commit dell'elemento del catalogo.
Esempio di richiesta
GET https://api.nuget.org/v3/catalog0/data/2017.11.02.00.40.00/netstandard1.4_lib.1.0.0-test.json
Risposta di esempio
{
"@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"
}
Cursore
Panoramica
Questa sezione descrive un concetto client che, sebbene non sia necessariamente obbligatorio dal protocollo, deve far parte di qualsiasi implementazione client del catalogo pratica.
Poiché il catalogo è una struttura di dati di sola accodamento indicizzata in base al tempo, il client deve archiviare un cursore in locale, che rappresenta fino al momento in cui il client ha elaborato gli elementi del catalogo. Si noti che questo valore del cursore non deve mai essere generato usando l'orologio del computer del client. Al contrario, il valore deve provenire dal valore di un oggetto catalogo commitTimestamp .
Ogni volta che il client vuole elaborare nuovi eventi nell'origine del pacchetto, è necessario eseguire una query solo sul catalogo per tutti gli elementi del catalogo con un timestamp di commit maggiore del cursore archiviato. Dopo che il client elabora correttamente tutti i nuovi elementi del catalogo, registra il timestamp di commit più recente degli elementi del catalogo appena elaborati come nuovo valore del cursore.
Usando questo approccio, il client può non perdere mai gli eventi del pacchetto che si sono verificati nell'origine del pacchetto. Inoltre, il client non deve mai rielaborare gli eventi precedenti prima del timestamp di commit registrato del cursore.
Questo potente concetto di cursori viene usato per molti processi in background nuget.org e viene usato per mantenere aggiornata l'API V3 stessa.
Valore iniziale
Quando il client del catalogo viene avviato per la prima volta (e pertanto non ha alcun valore di cursore), deve usare un valore di cursore predefinito di . System.DateTimeOffset.MinValue Net o una nozione analoga di timestamp minimo rappresentabile.
Iterazione sugli elementi del catalogo
Per eseguire una query per il set successivo di elementi del catalogo da elaborare, il client deve:
- Recuperare il valore del cursore registrato da un archivio locale.
- Scaricare e deserializzare l'indice del catalogo.
- Trovare tutte le pagine del catalogo con un timestamp di commit maggiore del cursore.
- Dichiarare un elenco vuoto di elementi del catalogo da elaborare.
- Per ogni pagina del catalogo corrispondente al passaggio 3:
- Scaricare e deserializzare la pagina del catalogo.
- Trovare tutti gli elementi del catalogo con un timestamp di commit maggiore del cursore.
- Aggiungere tutti gli elementi del catalogo corrispondenti all'elenco dichiarato nel passaggio 4.
- Ordinare l'elenco di elementi del catalogo in base al timestamp di commit.
- Elaborare ogni elemento del catalogo in sequenza:
- Scaricare e deserializzare l'elemento del catalogo.
- Reagire in modo appropriato al tipo di elemento del catalogo.
- Elaborare il documento dell'elemento del catalogo in modo specifico del client.
- Registrare il timestamp di commit dell'ultimo elemento del catalogo come nuovo valore del cursore.
Con questo algoritmo di base, l'implementazione client può creare una visualizzazione completa di tutti i pacchetti disponibili nell'origine del pacchetto. Il client deve eseguire periodicamente questo algoritmo per tenere sempre presenti le modifiche più recenti all'origine del pacchetto.
Nota
Si tratta dell'algoritmo usato nuget.org per mantenere aggiornate le risorse Package Metadata, Package Content, Search e Autocomplete .
Cursori dipendenti
Si supponga che siano presenti due client di catalogo che hanno una dipendenza intrinseca in cui l'output di un client dipende dall'output di un altro client.
Esempio
Ad esempio, in nuget.org un pacchetto appena pubblicato non dovrebbe essere visualizzato nella risorsa di ricerca prima che venga visualizzato nella risorsa dei metadati del pacchetto. Ciò è dovuto al fatto che l'operazione di "ripristino" eseguita dal client NuGet ufficiale usa la risorsa di metadati del pacchetto. Se un cliente individua un pacchetto usando il servizio di ricerca, dovrebbe essere in grado di ripristinare correttamente il pacchetto usando la risorsa dei metadati del pacchetto. In altre parole, la risorsa di ricerca dipende dalla risorsa metadati del pacchetto. Ogni risorsa ha un processo in background del client di catalogo che aggiorna tale risorsa. Ogni client ha il proprio cursore.
Poiché entrambe le risorse vengono compilate dal catalogo, il cursore del client di catalogo che aggiorna la risorsa di ricerca non deve superare il cursore del client del catalogo dei metadati del pacchetto.
Algoritmo
Per implementare questa restrizione, è sufficiente modificare l'algoritmo precedente in modo che sia:
- Recuperare il valore del cursore registrato da un archivio locale.
- Scaricare e deserializzare l'indice del catalogo.
- Trovare tutte le pagine del catalogo con un timestamp di commit maggiore del cursore minore o uguale al cursore della dipendenza.
- Dichiarare un elenco vuoto di elementi del catalogo da elaborare.
- Per ogni pagina del catalogo corrispondente al passaggio 3:
- Scaricare e deserializzare la pagina del catalogo.
- Trovare tutti gli elementi del catalogo con un timestamp di commit maggiore del cursore minore o uguale al cursore della dipendenza.
- Aggiungere tutti gli elementi del catalogo corrispondenti all'elenco dichiarato nel passaggio 4.
- Ordinare l'elenco di elementi del catalogo in base al timestamp di commit.
- Elaborare ogni elemento del catalogo in sequenza:
- Scaricare e deserializzare l'elemento del catalogo.
- Reagire in modo appropriato al tipo di elemento del catalogo.
- Elaborare il documento dell'elemento del catalogo in modo specifico del client.
- Registrare il timestamp di commit dell'ultimo elemento del catalogo come nuovo valore del cursore.
Usando questo algoritmo modificato, è possibile creare un sistema di client di catalogo dipendenti che producono tutti indici, artefatti specifici e così via.
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per