Wykaz
Wykaz jest zasobem, który rejestruje wszystkie operacje pakietu w źródle pakietu, takie jak tworzenie i usuwanie. Zasób wykazu ma Catalog typ w indeksie usługi. Tego zasobu można użyć do wykonywania zapytań dotyczących wszystkich opublikowanych pakietów.
Uwaga
Ponieważ wykaz nie jest używany przez oficjalnego klienta NuGet, nie wszystkie źródła pakietów implementują wykaz.
Uwaga
Obecnie katalog nuget.org nie jest dostępny w Chinach. Aby uzyskać więcej informacji, zobacz NuGet/NuGetGallery#4949.
Wersje
Używana jest następująca @type wartość:
| @type Wartość | Uwagi |
|---|---|
| Wykaz/3.0.0 | Wersja początkowa |
Podstawowy adres URL
Adres URL punktu wejścia dla następujących interfejsów API to wartość @id właściwości skojarzonej z wyżej wymienionymi wartościami zasobów @type . W tym temacie jest używany adres URL {@id}symbolu zastępczego .
Metody HTTP
Wszystkie adresy URL znalezione w zasobie wykazu obsługują tylko metody GET HTTP i HEAD.
Indeks wykazu
Indeks wykazu jest dokumentem w dobrze znanej lokalizacji, która zawiera listę elementów wykazu uporządkowaną chronologicznie. Jest to punkt wejścia zasobu wykazu.
Indeks składa się ze stron wykazu. Każda strona wykazu zawiera elementy wykazu. Każdy element wykazu reprezentuje zdarzenie dotyczące pojedynczego pakietu w danym momencie. Element wykazu może reprezentować pakiet, który został utworzony, nie wymieniony, ponownie wymieniony lub usunięty ze źródła pakietu. Przetwarzając elementy wykazu w kolejności chronologicznej, klient może utworzyć aktualny widok każdego pakietu, który istnieje w źródle pakietu w wersji 3.
Krótko mówiąc, obiekty blob wykazu mają następującą strukturę hierarchiczną:
- Indeks: punkt wejścia katalogu.
- Strona: grupowanie elementów wykazu.
- Liść: dokument reprezentujący element wykazu, który jest migawką stanu pojedynczego pakietu.
Każdy obiekt wykazu ma właściwość o nazwie commitTimeStamp reprezentującą, gdy element został dodany do wykazu. Elementy wykazu są dodawane do strony wykazu w partiach nazywanych zatwierdzeniami. Wszystkie elementy wykazu w tym samym zatwierdzeniu mają ten sam znacznik czasu zatwierdzenia (commitTimeStamp) i identyfikator zatwierdzenia (commitId). Elementy wykazu umieszczone w tym samym zatwierdzeniu reprezentują zdarzenia, które wystąpiły w tym samym punkcie w czasie w źródle pakietu. Nie ma kolejności w ramach zatwierdzenia wykazu.
Ponieważ każdy identyfikator pakietu i wersja są unikatowe, nigdy nie będzie więcej niż jeden element wykazu w zatwierdzeniu. Dzięki temu elementy wykazu dla pojedynczego pakietu zawsze mogą być jednoznacznie uporządkowane w odniesieniu do znacznika czasu zatwierdzenia.
Nigdy nie ma więcej niż jednego zatwierdzenia do wykazu na commitTimeStamp. Innymi słowy, element commitId jest nadmiarowy z elementem commitTimeStamp.
W przeciwieństwie do zasobu metadanych pakietu, który jest indeksowany według identyfikatora pakietu, wykaz jest indeksowany (i możliwy do wykonywania zapytań) tylko przez czas.
Elementy wykazu są zawsze dodawane do wykazu w monotonicznie rosnącej kolejności chronologicznej. Oznacza to, że jeśli zatwierdzenie wykazu zostanie dodane w czasie X, żadne zatwierdzenie wykazu nigdy nie zostanie dodane z czasem krótszym lub równym X.
Następujące żądanie pobiera indeks wykazu.
GET {@id}
Indeks wykazu jest dokumentem JSON zawierającym obiekt o następujących właściwościach:
| Nazwisko | Type | Wymagania | Uwagi |
|---|---|---|---|
| commitId | string | tak | Unikatowy identyfikator skojarzony z najnowszym zatwierdzeniem |
| commitTimeStamp | string | tak | Znacznik czasu ostatniego zatwierdzenia |
| count | integer | tak | Liczba stron w indeksie |
| elementy | tablica obiektów | tak | Tablica obiektów, każdy obiekt reprezentujący stronę |
Każdy element w tablicy items jest obiektem z minimalnymi szczegółami dotyczącymi każdej strony. Te obiekty strony nie zawierają liści wykazu (elementów). Kolejność elementów w tej tablicy nie jest zdefiniowana. Strony mogą być uporządkowane przez klienta w pamięci przy użyciu ich commitTimeStamp właściwości.
W miarę wprowadzania count nowych stron w tablicy będą one zwiększane, a nowe obiekty będą wyświetlane w tablicy items .
W miarę dodawania elementów do wykazu indeks commitId zmieni się i zwiększy się.commitTimeStamp Te dwie właściwości są zasadniczo podsumowaniem wszystkich stron commitId i commitTimeStamp wartości w tablicy items .
Obiekt strony wykazu w indeksie
Obiekty strony katalogu znajdujące się we właściwości indeksu items wykazu mają następujące właściwości:
| Nazwisko | Type | Wymagania | Uwagi |
|---|---|---|---|
| @id | string | tak | Adres URL pobierania strony wykazu |
| commitId | string | tak | Unikatowy identyfikator skojarzony z najnowszym zatwierdzeniem na tej stronie |
| commitTimeStamp | string | tak | Znacznik czasu ostatniego zatwierdzenia na tej stronie |
| count | integer | tak | Liczba elementów na stronie wykazu |
W przeciwieństwie do zasobu metadanych pakietu, który w niektórych przypadkach w wierszach opuszcza indeks, liście wykazu nigdy nie są wstawiane do indeksu i zawsze muszą być pobierane przy użyciu adresu URL strony @id .
Przykładowe żądanie
GET https://api.nuget.org/v3/catalog0/index.json
Przykładowa odpowiedź
{
"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
}
]
}
Strona wykazu
Strona wykazu jest kolekcją elementów wykazu. Jest to dokument pobrany przy użyciu jednej z @id wartości znalezionych w indeksie wykazu. Adres URL strony wykazu nie jest przewidywalny i powinien zostać odnaleziony przy użyciu tylko indeksu wykazu.
Nowe elementy wykazu są dodawane do strony w indeksie wykazu tylko z najwyższym znacznikiem czasu zatwierdzenia lub do nowej strony. Po dodaniu strony z wyższym znacznikiem czasu zatwierdzenia do wykazu starsze strony nigdy nie są dodawane ani zmieniane.
Dokument strony wykazu jest obiektem JSON o następujących właściwościach:
| Nazwisko | Type | Wymagania | Uwagi |
|---|---|---|---|
| commitId | string | tak | Unikatowy identyfikator skojarzony z najnowszym zatwierdzeniem na tej stronie |
| commitTimeStamp | string | tak | Znacznik czasu ostatniego zatwierdzenia na tej stronie |
| count | integer | tak | Liczba elementów na stronie |
| elementy | tablica obiektów | tak | Elementy wykazu na tej stronie |
| parent | string | tak | Adres URL indeksu wykazu |
Każdy element w tablicy items jest obiektem z minimalnymi szczegółami dotyczącymi elementu wykazu. Te obiekty elementów nie zawierają wszystkich danych elementu wykazu. Kolejność elementów w tablicy strony nie jest zdefiniowana items . Elementy mogą być uporządkowane przez klienta w pamięci przy użyciu ich commitTimeStamp właściwości.
Liczba elementów wykazu na stronie jest definiowana przez implementację serwera. W przypadku nuget.org na każdej stronie znajduje się co najwyżej 550 elementów, chociaż rzeczywista liczba może być mniejsza dla niektórych stron w zależności od rozmiaru następnej partii zatwierdzeń w danym momencie.
W miarę wprowadzania nowych elementów obiekt count jest zwiększany, a nowe obiekty elementów wykazu są wyświetlane w tablicy items .
W miarę dodawania elementów do strony commitId zmiany i commitTimeStamp wzrosty. Te dwie właściwości są zasadniczo podsumowaniem wszystkich commitId wartości i commitTimeStamp w tablicy items .
Obiekt elementu wykazu na stronie
Obiekty elementów wykazu znajdujące się we właściwości strony items wykazu mają następujące właściwości:
| Nazwisko | Type | Wymagania | Uwagi |
|---|---|---|---|
| @id | string | tak | Adres URL pobierania elementu wykazu |
| @type | string | tak | Typ elementu wykazu |
| commitId | string | tak | Identyfikator zatwierdzenia skojarzony z tym elementem wykazu |
| commitTimeStamp | string | tak | Sygnatura czasowa zatwierdzenia tego elementu wykazu |
| nuget:id | string | tak | Identyfikator pakietu powiązany z tym liściem |
| nuget:version | string | tak | Wersja pakietu powiązana z tym liściem |
Wartość @type będzie jedną z następujących dwóch wartości:
nuget:PackageDetails: odpowiadaPackageDetailstypowi w dokumencie liścia wykazu.nuget:PackageDelete: odpowiadaPackageDeletetypowi w dokumencie liścia wykazu.
Aby uzyskać więcej informacji o tym, co oznacza każdy typ, zobacz odpowiedni typ elementów poniżej.
Przykładowe żądanie
GET https://api.nuget.org/v3/catalog0/page2926.json
Przykładowa odpowiedź
{
"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"
}
]
}
Liść wykazu
Liść wykazu zawiera metadane dotyczące określonego identyfikatora pakietu i wersji w pewnym momencie. Jest to dokument pobrany przy użyciu wartości znalezionej @id na stronie wykazu. Adres URL liścia wykazu nie jest przewidywalny i powinien zostać odnaleziony przy użyciu tylko strony wykazu.
Dokument liścia wykazu jest obiektem JSON o następujących właściwościach:
| Nazwisko | Type | Wymagania | Uwagi |
|---|---|---|---|
| @type | ciąg lub tablica ciągów | tak | Typy elementu wykazu |
| catalog:commitId | string | tak | Identyfikator zatwierdzenia skojarzony z tym elementem wykazu |
| catalog:commitTimeStamp | string | tak | Sygnatura czasowa zatwierdzenia tego elementu wykazu |
| identyfikator | string | tak | Identyfikator pakietu elementu wykazu |
| Opublikowane | string | tak | Data publikacji elementu wykazu pakietów |
| version | string | tak | Wersja pakietu elementu wykazu |
Typy elementów
Właściwość @type jest ciągiem lub tablicą ciągów. Dla wygody, jeśli @type wartość jest ciągiem, powinna być traktowana jako dowolna tablica rozmiaru. Nie wszystkie możliwe wartości są @type udokumentowane. Jednak każdy element wykazu ma dokładnie jedną z dwóch następujących wartości typu ciągu:
PackageDetails: reprezentuje migawkę metadanych pakietuPackageDelete: reprezentuje pakiet, który został usunięty
Elementy wykazu szczegółów pakietu
Elementy wykazu z typem PackageDetails zawierają migawkę metadanych pakietu dla określonego pakietu (identyfikator i kombinacja wersji). Element wykazu szczegółów pakietu jest generowany, gdy źródło pakietu napotka dowolny z następujących scenariuszy:
- Pakiet jest wypychany.
- Zostanie ponownie wyświetlony pakiet.
- Pakiet nie znajduje się na liście.
- Pakiet jest przestarzały.
- Pakiet jest nieufazowany.
- Pakiet jest zmieniany.
- Zaktualizowano stan luki w zabezpieczeniach pakietu.
Zmiana przepływu pakietu jest gestem administracyjnym, który zasadniczo generuje fałszywe wypychanie istniejącego pakietu bez zmian w samym pakiecie. W nuget.org po naprawieniu usterki w jednym z zadań w tle używanych przez wykaz jest używany przepływ.
Klienci korzystający z elementów wykazu nie powinni próbować określić, które z tych scenariuszy wygenerowały element wykazu. Zamiast tego klient powinien po prostu zaktualizować dowolny zachowany widok lub indeks z metadanymi zawartymi w elemencie wykazu. Ponadto należy bezpiecznie obsłużyć zduplikowane lub nadmiarowe elementy wykazu (idempotentnie).
Elementy wykazu szczegółów pakietu mają następujące właściwości oprócz tych uwzględnionych we wszystkich liściach wykazu.
| Nazwisko | Type | Wymagania | Uwagi |
|---|---|---|---|
| Autorów | string | nie | |
| Utworzone | string | nie | Sygnatura czasowa pierwszego utworzenia pakietu. Właściwość rezerwowa: published. |
| dependencyGroups | tablica obiektów | nie | Zależności pakietu pogrupowane według platformy docelowej (taki sam format jak zasób metadanych pakietu) |
| Oczekiwany | obiekt | nie | Wycofanie skojarzone z pakietem (taki sam format jak zasób metadanych pakietu) |
| opis | string | nie | |
| iconUrl | string | nie | |
| isPrerelease | boolean | nie | Określa, czy wersja pakietu jest wersją wstępną. Można wykryć z versionpliku . |
| język | string | nie | |
| licenseUrl | string | nie | |
| wymienione | boolean | nie | Niezależnie od tego, czy pakiet jest wymieniony |
| minClientVersion | string | nie | |
| packageHash | string | tak | Skrót pakietu, kodowanie przy użyciu standardowej bazy 64 |
| packageHashAlgorithm | string | tak | |
| packageSize | integer | tak | Rozmiar pakietu .nupkg w bajtach |
| packageTypes | tablica obiektów | nie | Typy pakietów określone przez autora. |
| projectUrl | string | nie | |
| releaseNotes | string | nie | |
| requireLicenseAgreement | boolean | nie | Przyjmij false , jeśli zostanie wykluczona |
| Podsumowanie | string | nie | |
| tags | tablica ciągów | nie | |
| title | string | nie | |
| verbatimVersion | string | nie | Ciąg wersji, który pierwotnie został znaleziony w pliku .nuspec |
| Luki | tablica obiektów | nie | Luki w zabezpieczeniach pakietu |
Właściwość pakietu version jest pełnym ciągiem wersji po normalizacji. Oznacza to, że dane kompilacji SemVer 2.0.0 można uwzględnić tutaj.
Sygnatura created czasowa polega na tym, że pakiet został po raz pierwszy odebrany przez źródło pakietu, co zazwyczaj jest krótki czas przed sygnaturą czasową zatwierdzenia elementu wykazu.
Jest packageHashAlgorithm to ciąg zdefiniowany przez implementację serwera reprezentującą algorytm wyznaczania wartości skrótu używany do utworzenia elementu packageHash. nuget.org zawsze używać packageHashAlgorithm wartości SHA512.
Właściwość packageTypes będzie obecna tylko wtedy, gdy autor określił typ pakietu. Jeśli jest obecny, zawsze będzie miał co najmniej jeden (1) wpis. Każdy element w tablicy packageTypes jest obiektem JSON o następujących właściwościach:
| Nazwisko | Type | Wymagania | Uwagi |
|---|---|---|---|
| nazwa | string | tak | Nazwa typu pakietu. |
| version | string | nie | Wersja typu pakietu. Występuje tylko wtedy, gdy autor jawnie określił wersję w narzędziu nuspec. |
Sygnatura published czasowa to czas ostatniego wyświetlania pakietu.
Uwaga
W nuget.org wartość jest ustawiona na rok 1900, published gdy pakiet nie jest wymieniony.
Luki w zabezpieczeniach
Tablica vulnerability obiektów. Każda luka w zabezpieczeniach ma następujące właściwości:
| Nazwisko | Type | Wymagania | Uwagi |
|---|---|---|---|
| advisoryUrl | string | tak | Lokalizacja porad dotyczących zabezpieczeń pakietu |
| ważność | string | tak | Ważność porad: "0" = Niska, "1" = Umiarkowana, "2" = Wysoka, "3" = Krytyczne |
severity Jeśli właściwość zawiera wartości inne niż wymienione w tym miejscu, ważność porady ma być traktowana jako Niska.
Przykładowe żądanie
GET https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json
Przykładowa odpowiedź
{
"@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"
}
]
}
Usuwanie elementów wykazu pakietu
Elementy wykazu z typem PackageDelete zawierają minimalny zestaw informacji wskazujący klientom katalogu, że pakiet został usunięty ze źródła pakietu i nie jest już dostępny dla żadnej operacji pakietu (takiej jak przywracanie).
Uwaga
Istnieje możliwość usunięcia pakietu i późniejszego opublikowania go ponownie przy użyciu tego samego identyfikatora i wersji pakietu. W nuget.org jest to bardzo rzadki przypadek, ponieważ przerywa założenie oficjalnego klienta, że identyfikator pakietu i wersja oznaczają określoną zawartość pakietu. Aby uzyskać więcej informacji na temat usuwania pakietów w nuget.org, zobacz nasze zasady.
Elementy wykazu usuwania pakietu nie mają dodatkowych właściwości oprócz tych uwzględnionych we wszystkich liściach wykazu.
Właściwość version jest oryginalnym ciągiem wersji znajdującym się w pakiecie .nuspec.
Właściwość published to czas, w którym pakiet został usunięty, czyli zazwyczaj tak krótko, jak na znacznik czasu zatwierdzenia elementu wykazu.
Przykładowe żądanie
GET https://api.nuget.org/v3/catalog0/data/2017.11.02.00.40.00/netstandard1.4_lib.1.0.0-test.json
Przykładowa odpowiedź
{
"@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"
}
Kursor
Omówienie
W tej sekcji opisano koncepcję klienta, która chociaż nie musi być upoważniona przez protokół, powinna być częścią jakiejkolwiek praktycznej implementacji klienta katalogu.
Ponieważ katalog jest strukturą danych tylko do dołączania indeksowaną według czasu, klient powinien przechowywać kursor lokalnie, reprezentując maksymalnie punkt w czasie, w którym klient przetworzył elementy wykazu. Należy pamiętać, że ta wartość kursora nigdy nie powinna być generowana przy użyciu zegara komputera klienta. Zamiast tego wartość powinna pochodzić z wartości obiektu commitTimestamp wykazu.
Za każdym razem, gdy klient chce przetwarzać nowe zdarzenia w źródle pakietu, musi wysyłać zapytania tylko do wykazu dla wszystkich elementów wykazu z sygnaturą czasową zatwierdzenia większą niż przechowywany kursor. Po pomyślnym przetworzeniu wszystkich nowych elementów wykazu klient rejestruje najnowszy znacznik czasu zatwierdzenia elementów wykazu, który został właśnie przetworzony jako nowa wartość kursora.
Korzystając z tego podejścia, klient nie może przegapić żadnych zdarzeń pakietu, które wystąpiły w źródle pakietu. Ponadto klient nigdy nie musi ponownie przetwarzać starych zdarzeń przed zanotowany znacznik czasu zatwierdzenia kursora.
Ta zaawansowana koncepcja kursorów jest używana w wielu nuget.org zadaniach w tle i służy do aktualizowania samego interfejsu API w wersji 3.
Wartość początkowa
Gdy klient wykazu jest uruchamiany po raz pierwszy (i dlatego nie ma wartości kursora), powinien użyć domyślnej wartości kursora . Net System.DateTimeOffset.MinValue lub niektóre takie analogiczne pojęcie minimalnego godnego reprezentowania znacznika czasu.
Iterowanie elementów wykazu
Aby wykonać zapytanie dotyczące następnego zestawu elementów wykazu do przetworzenia, klient powinien:
- Pobierz zarejestrowaną wartość kursora z magazynu lokalnego.
- Pobierz i deserializuj indeks wykazu.
- Znajdź wszystkie strony wykazu z sygnaturą czasową zatwierdzenia większą niż kursor.
- Zadeklaruj pustą listę elementów wykazu do przetworzenia.
- Dla każdej strony wykazu dopasowanej w kroku 3:
- Pobierz i zdeserializuje stronę wykazu.
- Znajdź wszystkie elementy wykazu z sygnaturą czasową zatwierdzenia większą niż kursor.
- Dodaj wszystkie pasujące elementy wykazu do listy zadeklarowanej w kroku 4.
- Sortuj listę elementów wykazu według znacznika czasu zatwierdzenia.
- Przetwarzaj każdy element wykazu w sekwencji:
- Pobierz i deserializuj element wykazu.
- Odpowiednio zareaguj na typ elementu wykazu.
- Przetwarzanie dokumentu elementu wykazu w sposób specyficzny dla klienta.
- Zarejestruj znacznik czasu zatwierdzenia ostatniego elementu wykazu jako nową wartość kursora.
Za pomocą tego podstawowego algorytmu implementacja klienta może utworzyć pełny widok wszystkich pakietów dostępnych w źródle pakietu. Klient musi okresowo wykonywać ten algorytm tylko wtedy, aby zawsze był świadomy najnowszych zmian w źródle pakietu.
Uwaga
Jest to algorytm, który nuget.org używa do przechowywania aktualnych zasobów metadanych pakietu, zawartości pakietu, wyszukiwania i autouzupełniania .
Kursory zależne
Załóżmy, że istnieją dwa klienci katalogu, którzy mają nieodłączną zależność, w której dane wyjściowe jednego klienta zależą od danych wyjściowych innego klienta.
Przykład
Na przykład w nuget.org nowo opublikowany pakiet nie powinien być wyświetlany w zasobie wyszukiwania, zanim pojawi się on w zasobie metadanych pakietu. Dzieje się tak, ponieważ operacja "restore" wykonywana przez oficjalnego klienta NuGet używa zasobu metadanych pakietu. Jeśli klient odnajdzie pakiet przy użyciu usługi wyszukiwania, powinien mieć możliwość pomyślnego przywrócenia tego pakietu przy użyciu zasobu metadanych pakietu. Innymi słowy, zasób wyszukiwania zależy od zasobu metadanych pakietu. Każdy zasób ma zadanie w tle klienta wykazu, które aktualizuje ten zasób. Każdy klient ma własny kursor.
Ponieważ oba zasoby są tworzone poza wykazem, kursor klienta wykazu, który aktualizuje zasób wyszukiwania, nie może wykraczać poza kursor klienta wykazu metadanych pakietu.
Algorytm
Aby zaimplementować to ograniczenie, po prostu zmodyfikuj powyższy algorytm tak, aby był następujący:
- Pobierz zarejestrowaną wartość kursora z magazynu lokalnego.
- Pobierz i deserializuj indeks wykazu.
- Znajdź wszystkie strony wykazu ze znacznikiem czasu zatwierdzenia większym niż kursor mniejszy lub równy kursorowi zależności.
- Zadeklaruj pustą listę elementów wykazu do przetworzenia.
- Dla każdej strony wykazu dopasowanej w kroku 3:
- Pobierz i zdeserializuje stronę wykazu.
- Znajdź wszystkie elementy wykazu ze znacznikiem czasu zatwierdzenia większym niż kursor mniejszy lub równy kursorowi zależności.
- Dodaj wszystkie pasujące elementy wykazu do listy zadeklarowanej w kroku 4.
- Sortuj listę elementów wykazu według znacznika czasu zatwierdzenia.
- Przetwarzaj każdy element wykazu w sekwencji:
- Pobierz i deserializuj element wykazu.
- Odpowiednio zareaguj na typ elementu wykazu.
- Przetwarzanie dokumentu elementu wykazu w sposób specyficzny dla klienta.
- Zarejestruj znacznik czasu zatwierdzenia ostatniego elementu wykazu jako nową wartość kursora.
Korzystając z tego zmodyfikowanego algorytmu, można utworzyć system klientów wykazu zależnego, tworząc własne indeksy, artefakty itp.