Dotaz na všechny balíčky publikované do nuget.org

Jedním z běžných vzorů dotazů ve starší verzi rozhraní API OData V2 bylo vytvoření výčtu všech balíčků publikovaných do nuget.org seřazených při publikování balíčku. Scénáře vyžadující tento druh dotazu na nuget.org se značně liší:

• Úplná replikace nuget.org
• Zjištění, kdy mají balíčky vydané nové verze
• Vyhledání balíčků, které závisí na vašem balíčku

Starší způsob, jak to udělat, obvykle závisí na řazení entity balíčku OData podle časového razítka a stránkování v masivní sadě výsledků pomocí skip parametrů a top (velikost stránky). Tento přístup má bohužel některé nevýhody:

• Možnost chybějících balíčků, protože dotazy se provádějí na datech, která často mění pořadí
• Doba odezvy pomalých dotazů, protože dotazy nejsou optimalizované (nejoptimaličtější dotazy jsou ty, které podporují hlavní scénář pro oficiálního klienta NuGet).
• Použití zastaralého a nezdokumentovaného rozhraní API, což znamená, že podpora těchto dotazů v budoucnu není zaručená.
• Nemožnost přehrání historie v přesném pořadí, v jakém se prohrála

Z tohoto důvodu je možné sledovat následující příručku, která řeší výše uvedené scénáře spolehlivějším způsobem a způsobem kontroly budoucnosti.

Přehled

Uprostřed tohoto průvodce je prostředek v rozhraní NUGet API označované jako katalog. Katalog je rozhraní API jen pro připojení, které volajícímu umožňuje zobrazit úplnou historii balíčků přidaných do nuget.org, změněných a odstraněných z nuget.org. Pokud vás zajímají všechny nebo dokonce i podmnožiny balíčků publikovaných do nuget.org, je katalog skvělý způsob, jak zůstat v aktualizovaném stavu se sadou aktuálně dostupných balíčků, jak to bude v čase.

Tato příručka je určená jako podrobný návod, ale pokud vás zajímají podrobné podrobnosti o katalogu, podívejte se na referenční dokument k rozhraní API.

Následující kroky je možné implementovat v libovolném programovacím jazyce podle vašeho výběru. Pokud chcete úplnou spuštěnou ukázku, podívejte se na níže uvedenou ukázku jazyka C#.

V opačném případě postupujte podle níže uvedených pokynů a sestavte spolehlivou čtečku katalogu.

Inicializace kurzoru

Prvním krokem při vytváření spolehlivého čtenáře katalogu je implementace kurzoru. Úplné podrobnosti o návrhu kurzoru katalogu najdete v referenčním dokumentu katalogu. Stručně řečeno, kurzor je bod v čase, do kterého jste zpracovali události v katalogu. Události v katalogu představují publikování balíčků a další změny balíčku. Pokud vám záleží na všech balíčcích publikovaných v NuGetu (od začátku času), inicializovali byste kurzor na časové razítko minimální hodnoty (např. DateTime.MinValue v .NET). Pokud vás zajímají jenom balíčky publikované odteď, použili byste aktuální časové razítko jako počáteční hodnotu kurzoru.

V tomto průvodci inicializujeme kurzor na časové razítko před hodinou. Prozatím toto časové razítko uložte do paměti.

DateTime cursor = DateTime.UtcNow.AddHours(-1);

Určení adresy URL indexu katalogu

Umístění každého prostředku (koncového bodu) v rozhraní NUGet API by se mělo zjistit pomocí indexu služby. Vzhledem k tomu, že se tento průvodce zaměřuje na nuget.org, budeme používat index služeb nuget.org.

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

Dokument služby je dokument JSON obsahující všechny prostředky na nuget.org. Vyhledejte prostředek, který má @type hodnotu Catalog/3.0.0vlastnosti . @id Přidružená hodnota vlastnosti je adresa URL samotného indexu katalogu.

Vyhledání nových listů katalogu

@id Pomocí hodnoty vlastnosti nalezené v předchozím kroku stáhněte index katalogu:

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

Deserializace indexu katalogu Vyfiltrujte všechny objekty stránky katalogu, které mají commitTimeStamp menší nebo rovnou aktuální hodnotě kurzoru.

Pro každou zbývající stránku katalogu stáhněte celý dokument pomocí @id vlastnosti.

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

Deserializovat stránku katalogu. Vyfiltrujte všechny objekty typu list katalogu s commitTimeStamp hodnotou menší než nebo rovno aktuální hodnotě kurzoru.

Po stažení všech stránek katalogu, které nejsou odfiltrované, máte sadu objektů typu list katalogu představující balíčky, které byly publikovány, nezařazené, uvedené nebo odstraněny v době mezi časovým razítkem kurzoru a nyní.

Procesové listy katalogu

V tuto chvíli můžete u položek katalogu provádět jakékoli vlastní zpracování, které byste chtěli. Pokud potřebujete jen ID a verzi balíčku, můžete zkontrolovat nuget:id a nuget:version vlastnosti objektů položek katalogu nalezených na stránkách. Nezapomeňte se podívat na @type vlastnost, abyste věděli, jestli se položka katalogu týká existujícího balíčku nebo odstraněného balíčku.

Pokud vás zajímají metadata o balíčku (například popis, závislosti, velikost .nupkg atd.), můžete pomocí vlastnosti načíst dokument@id typu list katalogu.

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

Tento dokument obsahuje všechna metadata zahrnutá v prostředku metadat balíčku a další.

V tomto kroku implementujete vlastní logiku. Další kroky v této příručce jsou implementovány prakticky stejným způsobem, bez ohledu na to, co děláte s listy katalogu.

Stažení souboru .nupkg

Pokud chcete stáhnout balíček .nupkg pro balíčky nalezené v katalogu, můžete použít prostředek obsahu balíčku. Všimněte si však, že mezi nalezením balíčku v katalogu a dostupností v prostředku obsahu balíčku je krátká prodleva. Pokud se tedy setkáte 404 Not Found při pokusu o stažení souboru .nupkg pro balíček, který jste našli v katalogu, zkuste to znovu krátce později. Oprava tohoto zpoždění sleduje problém NuGet/NuGetGallery#3455 na GitHubu.

Přesunutí kurzoru dopředu

Po úspěšném zpracování položek katalogu je nutné určit novou hodnotu kurzoru, kterou chcete uložit. Uděláte to tak, že vyhledáte maximální (nejnovější chronologicky) commitTimeStamp všech zpracovaných položek katalogu. Toto je nová hodnota kurzoru. Uložte ho do nějakého trvalého úložiště, jako je databáze, systém souborů nebo úložiště objektů blob. Pokud chcete získat více položek katalogu, jednoduše začněte od prvního kroku inicializací hodnoty kurzoru z tohoto trvalého úložiště.

Pokud vaše aplikace vyvolá výjimku nebo chyby, nepřesouvejte kurzor dopředu. Přesunutí kurzoru dopředu znamená, že před kurzorem už nikdy nebudete muset zpracovávat položky katalogu.

Pokud z nějakého důvodu máte chybu v tom, jak katalog zpracováváte, můžete jednoduše přesunout kurzor zpět v čase a umožnit kódu znovu zpracovat staré položky katalogu.

Ukázkový kód jazyka C#

Vzhledem k tomu, že katalog je sada dokumentů JSON dostupných přes HTTP, může být interagována s libovolným programovacím jazykem, který má klienta HTTP a deserializátor JSON.

Ukázky jazyka C# jsou k dispozici v úložišti NuGet/Samples.

git clone https://github.com/NuGet/Samples.git

Sada SDK katalogu

Nejjednodušší způsob, jak katalog využívat, je použít předem vydaný balíček NuGet.Protocol.Catalogsady SDK katalogu .NET, který je k dispozici v Azure Artifacts pomocí následující adresy URL zdroje balíčku NuGet: https://pkgs.dev.azure.com/dnceng/public/_packaging/nuget-build/nuget/v3/index.json.

Tento balíček můžete nainstalovat do projektu kompatibilního s netstandard1.3 nebo novějším (například rozhraní .NET Framework 4.6).

Ukázka používající tento balíček je k dispozici na GitHubu v projektu NuGet.Protocol.Catalog.Sample.

Ukázkový výstup

2017-11-10T22:16:44.8689025+00:00: Found package details leaf for xSkrape.APIWrapper.REST 1.0.2.
2017-11-10T22:16:54.6972769+00:00: Found package details leaf for xSkrape.APIWrapper.REST 1.0.1.
2017-11-10T22:19:20.6385542+00:00: Found package details leaf for Platform.EnUnity 1.0.8.
...
2017-11-10T23:05:04.9695890+00:00: Found package details leaf for xSkrape.APIWrapper.Base 1.0.1.
2017-11-10T23:05:04.9695890+00:00: Found package details leaf for xSkrape.APIWrapper.Base 1.0.2.
2017-11-10T23:07:23.1303569+00:00: Found package details leaf for VeiculoX.Model 0.0.15.
Processing the catalog leafs failed. Retrying.
fail: NuGet.Protocol.Catalog.LoggerCatalogLeafProcessor[0]
      10 catalog commits have been processed. We will now simulate a failure.
warn: NuGet.Protocol.Catalog.CatalogProcessor[0]
      Failed to process leaf https://api.nuget.org/v3/catalog0/data/2017.11.10.23.07.23/veiculox.model.0.0.15.json (VeiculoX.Model 0.0.15, PackageDetails).
warn: NuGet.Protocol.Catalog.CatalogProcessor[0]
      13 out of 59 leaves were left incomplete due to a processing failure.
warn: NuGet.Protocol.Catalog.CatalogProcessor[0]
      1 out of 1 pages were left incomplete due to a processing failure.
2017-11-10T23:07:23.1303569+00:00: Found package details leaf for VeiculoX.Model 0.0.15.
2017-11-10T23:07:33.0212446+00:00: Found package details leaf for VeiculoX.Model 0.0.14.
2017-11-10T23:07:41.6621837+00:00: Found package details leaf for VeiculoX.Model 0.0.13.
2017-11-10T23:09:58.5728614+00:00: Found package details leaf for CreaSoft.Composition.Web.Extensions 1.1.0.
2017-11-10T23:09:58.5728614+00:00: Found package details leaf for DarkXaHTeP.Extensions.Configuration.Consul 0.0.4.
2017-11-10T23:09:58.5728614+00:00: Found package details leaf for xSkrape.APIWrapper.REST.Sample 1.0.3.
2017-11-10T23:10:09.0574930+00:00: Found package details leaf for Microsoft.VisualStudio.Imaging 15.4.27004.
2017-11-10T23:10:09.0574930+00:00: Found package details leaf for Microsoft.VisualStudio.Imaging.Interop.14.0.DesignTime 14.3.25407.
2017-11-10T23:10:09.0574930+00:00: Found package details leaf for Microsoft.VisualStudio.Language.Intellisense 15.4.27004.
2017-11-10T23:10:09.0574930+00:00: Found package details leaf for Microsoft.VisualStudio.Language.StandardClassification 15.4.27004.
2017-11-10T23:10:09.0574930+00:00: Found package details leaf for Microsoft.VisualStudio.ManagedInterfaces 8.0.50727.
2017-11-10T23:10:09.0574930+00:00: Found package details leaf for xSkrape.APIWrapper.REST.Sample 1.0.2.
2017-11-10T23:10:09.0574930+00:00: Found package details leaf for xSkrape.APIWrapper.REST.Sample 1.0.3.

Minimální ukázka

Příklad s menším počtem závislostí, které ilustrují interakci s katalogem podrobněji, naleznete v ukázkovém projektu CatalogReaderExample. Cíle projektu netcoreapp2.0 a závisí na NuGet.Protocol 4.4.0 (pro překlad indexu služby) a Newtonsoft.Json 9.0.1 (pro deserializaci JSON).

Hlavní logika kódu je viditelná v souboru Program.cs.

Ukázkový výstup

No cursor found. Defaulting to 11/2/2017 9:41:28 PM.
Fetched catalog index https://api.nuget.org/v3/catalog0/index.json.
Fetched catalog page https://api.nuget.org/v3/catalog0/page2935.json.
Processing 69 catalog leaves.
11/2/2017 9:32:35 PM: DotVVM.Compiler.Light 1.1.7 (type is nuget:PackageDetails)
11/2/2017 9:32:35 PM: Momentum.Pm.Api 5.12.181-beta (type is nuget:PackageDetails)
11/2/2017 9:32:44 PM: Momentum.Pm.PortalApi 5.12.181-beta (type is nuget:PackageDetails)
11/2/2017 9:35:14 PM: Genesys.Extensions.Standard 3.17.11.40 (type is nuget:PackageDetails)
11/2/2017 9:35:14 PM: Genesys.Extensions.Core 3.17.11.40 (type is nuget:PackageDetails)
11/2/2017 9:35:14 PM: Halforbit.DataStores.FileStores.Serialization.Bond 1.0.4 (type is nuget:PackageDetails)
11/2/2017 9:35:14 PM: Halforbit.DataStores.FileStores.AmazonS3 1.0.4 (type is nuget:PackageDetails)
11/2/2017 9:35:14 PM: Halforbit.DataStores.DocumentStores.DocumentDb 1.0.6 (type is nuget:PackageDetails)
11/2/2017 9:35:14 PM: Halforbit.DataStores.FileStores.BlobStorage 1.0.5 (type is nuget:PackageDetails)
...
11/2/2017 10:23:54 PM: Cake.GitPackager 0.1.2 (type is nuget:PackageDetails)
11/2/2017 10:23:54 PM: UtilPack.NuGet 2.0.0 (type is nuget:PackageDetails)
11/2/2017 10:23:54 PM: UtilPack.NuGet.AssemblyLoading 2.0.0 (type is nuget:PackageDetails)
11/2/2017 10:26:26 PM: UtilPack.NuGet.Deployment 2.0.0 (type is nuget:PackageDetails)
11/2/2017 10:26:26 PM: UtilPack.NuGet.Common.MSBuild 2.0.0 (type is nuget:PackageDetails)
11/2/2017 10:26:36 PM: InstaClient 1.0.2 (type is nuget:PackageDetails)
11/2/2017 10:26:36 PM: SecureStrConvertor.VARUN_RUSIYA 1.0.0.5 (type is nuget:PackageDetails)
Writing cursor value: 11/2/2017 10:26:36 PM.