Bagikan melalui

Kueri untuk semua paket yang diterbitkan ke nuget.org

  • Artikel

Salah satu pola kueri umum pada API OData V2 warisan adalah menghitung semua paket yang diterbitkan ke nuget.org, diurutkan oleh ketika paket diterbitkan. Skenario yang memerlukan kueri semacam ini terhadap nuget.org sangat bervariasi:

  • Mereplikasi nuget.org sepenuhnya
  • Mendeteksi kapan paket memiliki versi baru yang dirilis
  • Menemukan paket yang bergantung pada paket Anda

Cara warisan untuk melakukan ini biasanya tergantung pada pengurutan entitas paket OData dengan tanda waktu dan penomoran di seluruh tataan hasil besar-besaran menggunakan skip parameter dan top (ukuran halaman). Sayangnya, pendekatan ini memiliki beberapa kelemahan:

  • Kemungkinan paket yang hilang, karena kueri sedang dibuat pada data yang sering mengubah urutan
  • Waktu respons kueri lambat, karena kueri tidak dioptimalkan (kueri yang paling dioptimalkan adalah kueri yang mendukung skenario utama untuk klien NuGet resmi)
  • Penggunaan API yang tidak digunakan lagi dan tidak terdokumentasi, yang berarti dukungan kueri tersebut di masa mendatang tidak dijamin
  • Ketidakmampuan untuk memutar ulang riwayat dalam urutan yang tepat yang ditranspirasinya

Untuk alasan ini, panduan berikut dapat diikuti untuk mengatasi skenario tersebut dengan cara yang lebih andal dan tahan di masa mendatang.

Gambaran Umum

Di tengah panduan ini adalah sumber daya di API NuGet yang disebut katalog. Katalog adalah API khusus tambahan yang memungkinkan pemanggil untuk melihat riwayat lengkap paket yang ditambahkan ke, dimodifikasi, dan dihapus dari nuget.org. Jika Anda tertarik pada semua atau bahkan subset paket yang diterbitkan ke nuget.org, katalog adalah cara yang bagus untuk tetap up-to-date dengan set paket yang saat ini tersedia seiring berjalannya waktu.

Panduan ini dimaksudkan untuk menjadi panduan tingkat tinggi tetapi jika Anda tertarik dengan detail detail halus katalog, lihat dokumen referensi API-nya.

Langkah-langkah berikut dapat diimplementasikan dalam bahasa pemrograman apa pun pilihan Anda. Jika Anda menginginkan sampel yang berjalan penuh, lihat sampel C# yang disebutkan di bawah ini.

Jika tidak, ikuti panduan di bawah ini untuk membangun pembaca katalog yang andal.

Menginisialisasi kursor

Langkah pertama dalam membangun pembaca katalog yang andal adalah menerapkan kursor. Untuk detail selengkapnya tentang desain kursor katalog, lihat dokumen referensi katalog. Singkatnya, kursor adalah titik waktu yang telah Anda proses peristiwa dalam katalog. Peristiwa dalam katalog mewakili penerbitan paket dan perubahan paket lainnya. Jika Anda peduli tentang semua paket yang pernah diterbitkan ke NuGet (sejak awal waktu), Anda akan menginisialisasi kursor Anda ke tanda waktu "nilai minimum" (misalnya DateTime.MinValue dalam .NET). Jika Anda hanya peduli tentang paket yang diterbitkan mulai sekarang, Anda akan menggunakan tanda waktu saat ini sebagai nilai kursor awal Anda.

Untuk panduan ini, kami akan menginisialisasi kursor ke tanda waktu satu jam yang lalu. Untuk saat ini, simpan tanda waktu tersebut dalam memori.

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

Menentukan URL indeks katalog

Lokasi setiap sumber daya (titik akhir) di NUGet API harus ditemukan menggunakan indeks layanan. Karena panduan ini berfokus pada nuget.org, kita akan menggunakan indeks layanan nuget.org.

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

Dokumen layanan adalah dokumen JSON yang berisi semua sumber daya pada nuget.org. Cari sumber daya yang @type memiliki nilai properti .Catalog/3.0.0 Nilai properti terkait @id adalah URL ke indeks katalog itu sendiri.

Menemukan daun katalog baru

Menggunakan nilai properti yang @id ditemukan di langkah sebelumnya, unduh indeks katalog:

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

Deserialisasi indeks katalog. Filter semua objek halaman katalog dengan commitTimeStamp kurang dari atau sama dengan nilai kursor Anda saat ini.

Untuk setiap halaman katalog yang tersisa, unduh dokumen lengkap menggunakan @id properti .

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

Deserialisasi halaman katalog. Filter semua objek daun katalog dengan commitTimeStamp kurang dari atau sama dengan nilai kursor Anda saat ini.

Setelah mengunduh semua halaman katalog yang tidak difilter, Anda memiliki sekumpulan objek daun katalog yang mewakili paket yang telah diterbitkan, tidak terdaftar, tercantum, atau dihapus dalam waktu antara tanda waktu kursor Anda dan sekarang.

Memproses daun katalog

Pada titik ini, Anda dapat melakukan pemrosesan kustom apa pun yang Anda inginkan pada item katalog. Jika yang Anda butuhkan adalah ID dan versi paket, Anda dapat memeriksa nuget:id properti dan nuget:version pada objek item katalog yang ditemukan di halaman. Pastikan untuk melihat @type properti untuk mengetahui apakah item katalog menyangkut paket yang ada atau paket yang dihapus.

Jika Anda tertarik dengan metadata tentang paket (seperti deskripsi, dependensi, ukuran .nupkg, dll), Anda dapat mengambil dokumen daun katalog menggunakan @id properti .

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

Dokumen ini memiliki semua metadata yang disertakan dalam sumber daya metadata paket, dan banyak lagi!

Langkah ini adalah tempat Anda menerapkan logika kustom Anda. Langkah-langkah lain dalam panduan ini diimplementasikan dengan cara yang sama tidak peduli apa yang Anda lakukan dengan daun katalog.

Mengunduh .nupkg

Jika Anda tertarik untuk mengunduh .nupkg untuk paket yang ditemukan di katalog, Anda dapat menggunakan sumber daya konten paket. Namun, perhatikan bahwa ada penundaan singkat antara ketika paket ditemukan di katalog dan ketika tersedia di sumber daya konten paket. Oleh karena itu, jika Anda menemukan 404 Not Found ketika mencoba mengunduh .nupkg untuk paket yang Anda temukan di katalog, cukup coba lagi beberapa saat kemudian. Memperbaiki penundaan ini dilacak oleh masalah GitHub NuGet/NuGetGallery#3455.

Memindahkan kursor ke depan

Setelah berhasil memproses item katalog, Anda perlu menentukan nilai kursor baru untuk disimpan. Untuk melakukan ini, temukan maksimum (secara kronologis terbaru) commitTimeStamp dari semua item katalog yang Anda proses. Ini adalah nilai kursor baru Anda. Simpan ke beberapa penyimpanan persisten, seperti database, sistem file, atau penyimpanan blob. Ketika Anda ingin mendapatkan lebih banyak item katalog, cukup mulai dari langkah pertama dengan menginisialisasi nilai kursor Anda dari penyimpanan persisten ini.

Jika aplikasi Anda melemparkan pengecualian atau kesalahan, jangan pindahkan kursor ke depan. Memindahkan kursor ke depan memiliki arti bahwa Anda tidak perlu lagi memproses item katalog sebelum kursor Anda.

Jika, untuk beberapa alasan, Anda memiliki bug dalam cara Anda memproses daun katalog, Anda cukup memindahkan kursor Anda ke belakang dalam waktu dan memungkinkan kode Anda untuk memproses ulang item katalog lama.

Kode sampel C#

Karena katalog adalah sekumpulan dokumen JSON yang tersedia melalui HTTP, katalog dapat berinteraksi dengan menggunakan bahasa pemrograman apa pun yang memiliki klien HTTP dan deserializer JSON.

Sampel C# tersedia di repositori NuGet/Samples.

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

SDK Katalog

Cara term mudah untuk menggunakan katalog adalah dengan menggunakan paket NuGet.Protocol.CatalogSDK katalog .NET pra-rilis , yang tersedia di Azure Artifacts menggunakan URL sumber paket NuGet berikut: https://pkgs.dev.azure.com/dnceng/public/_packaging/nuget-build/nuget/v3/index.json.

Anda dapat menginstal paket ini ke proyek yang kompatibel dengan netstandard1.3 atau lebih besar (seperti .NET Framework 4.6).

Sampel yang menggunakan paket ini tersedia di GitHub dalam proyek NuGet.Protocol.Catalog.Sample.

Sampel output

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.

Sampel minimal

Untuk contoh dengan lebih sedikit dependensi yang mengilustrasikan interaksi dengan katalog secara lebih rinci, lihat proyek sampel CatalogReaderExample. Proyek menargetkan netcoreapp2.0 dan tergantung pada NuGet.Protocol 4.4.0 (untuk menyelesaikan indeks layanan) dan Newtonsoft.Json 9.0.1 (untuk deserialisasi JSON).

Logika utama kode terlihat dalam file Program.cs.

Sampel output

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.