Metadata paket
Dimungkinkan untuk mengambil metadata tentang paket yang tersedia pada sumber paket menggunakan API NuGet V3. Metadata ini dapat diambil menggunakan sumber daya yang RegistrationsBaseUrl ditemukan dalam indeks layanan.
Pengumpulan dokumen yang ditemukan di bawah RegistrationsBaseUrl sering disebut "pendaftaran" atau "blob pendaftaran". Kumpulan dokumen di bawah satu RegistrationsBaseUrl disebut sebagai "sarang pendaftaran". Sarang pendaftaran berisi metadata tentang setiap paket yang tersedia di sumber paket.
Catatan
Sumber daya metadata paket tidak berisi semua metadata untuk paket. Gunakan sumber daya pencarian untuk menemukan pemilik paket, unduhan, atau status reservasi awalan.
Penerapan versi
Nilai berikut @type digunakan:
| @type nilai | Catatan |
|---|---|
| RegistrationsBaseUrl | Rilis awal |
| RegistrationsBaseUrl/3.0.0-beta | Alias dari RegistrationsBaseUrl |
| RegistrationsBaseUrl/3.0.0-rc | Alias dari RegistrationsBaseUrl |
| RegistrationsBaseUrl/3.4.0 | Respons gzipped |
| RegistrationsBaseUrl/3.6.0 | Termasuk paket SemVer 2.0.0 |
Ini mewakili tiga sarang pendaftaran berbeda yang tersedia untuk berbagai versi klien.
RegistrationsBaseUrl
Pendaftaran ini tidak dikompresi (artinya mereka menggunakan tersirat Content-Encoding: identity). Paket SemVer 2.0.0 dikecualikan dari sarang ini.
RegistrationsBaseUrl/3.4.0
Pendaftaran ini dikompresi menggunakan Content-Encoding: gzip. Paket SemVer 2.0.0 dikecualikan dari sarang ini.
RegistrationsBaseUrl/3.6.0
Pendaftaran ini dikompresi menggunakan Content-Encoding: gzip. Paket SemVer 2.0.0 disertakan dalam sarang ini.
Untuk informasi selengkapnya tentang SemVer 2.0.0, lihat Dukungan SemVer 2.0.0 untuk nuget.org.
URL Dasar
URL dasar untuk API berikut adalah nilai properti yang @id terkait dengan nilai sumber daya @type yang disebutkan di atas. Dalam dokumen berikut, URL {@id} dasar tempat penampung akan digunakan. URL dasar dapat berubah berdasarkan implementasi atau perubahan infrastruktur dalam sumber paket sehingga harus diambil secara dinamis dari indeks layanan oleh perangkat lunak klien.
Metode HTTP
Semua URL yang ditemukan di sumber daya pendaftaran mendukung metode GET HTTP dan HEAD.
Indeks pendaftaran
Metadata paket grup sumber daya pendaftaran berdasarkan ID paket. Tidak dimungkinkan untuk mendapatkan data tentang lebih dari satu ID paket pada satu waktu. Sumber daya ini tidak menyediakan cara untuk menemukan ID paket. Sebaliknya, klien diasumsikan sudah mengetahui ID paket yang diinginkan. Metadata yang tersedia tentang setiap versi paket bervariasi menurut implementasi server. Blob pendaftaran paket memiliki struktur hierarkis berikut:
- Indeks: titik masuk untuk metadata paket, dibagikan oleh semua paket pada sumber dengan ID paket yang sama.
- Halaman: pengelompokan versi paket. Jumlah versi paket dalam halaman ditentukan oleh implementasi server.
- Daun: dokumen khusus untuk versi paket tunggal.
URL indeks pendaftaran dapat diprediksi dan dapat ditentukan oleh klien yang diberi ID paket dan nilai sumber daya @id pendaftaran dari indeks layanan. URL untuk halaman pendaftaran dan daun ditemukan dengan memeriksa indeks pendaftaran.
Halaman pendaftaran dan daun
Meskipun tidak benar-benar diperlukan untuk implementasi server untuk menyimpan daun pendaftaran dalam dokumen halaman pendaftaran terpisah, ini adalah praktik yang disarankan untuk menghemat memori sisi klien. Alih-alih menginlining semua daun pendaftaran dalam indeks atau segera menyimpan daun dalam dokumen halaman, disarankan agar implementasi server menentukan beberapa heuristik untuk memilih antara dua pendekatan berdasarkan jumlah versi paket atau ukuran kumulatif daun paket.
Menyimpan semua versi paket (daun) dalam indeks pendaftaran menghemat jumlah permintaan HTTP yang diperlukan untuk mengambil metadata paket tetapi berarti bahwa dokumen yang lebih besar harus diunduh dan lebih banyak memori klien harus dialokasikan. Di sisi lain, jika implementasi server segera menyimpan pendaftaran meninggalkan dokumen halaman terpisah, klien harus melakukan lebih banyak permintaan HTTP untuk mendapatkan informasi yang dibutuhkan.
Heuristik yang nuget.org gunakan adalah sebagai berikut: jika ada 128 atau lebih versi paket, pecahkan daun menjadi halaman berukuran 64. Jika ada kurang dari 128 versi, sebaris semua pergi ke indeks pendaftaran. Perhatikan bahwa ini berarti paket dengan versi 65 hingga 127 akan memiliki dua halaman dalam indeks tetapi kedua halaman akan di-inlin.
GET {@id}/{LOWER_ID}/index.json
Parameter permintaan
| Nama | Dalam | Jenis | Diperlukan | Catatan |
|---|---|---|---|---|
| LOWER_ID | URL | string | yes | ID paket, huruf kecil |
Nilainya LOWER_ID adalah ID paket yang diinginkan yang diturunkan menggunakan aturan yang diterapkan oleh . System.String.ToLowerInvariant() Metode NET.
Respons
Responsnya adalah dokumen JSON yang memiliki objek akar dengan properti berikut:
| Nama | Tipe | Diperlukan | Catatan |
|---|---|---|---|
| jumlah | Integer | yes | Jumlah halaman pendaftaran dalam indeks |
| item | array objek | yes | Array halaman pendaftaran |
Setiap item dalam array objek items indeks adalah objek JSON yang mewakili halaman pendaftaran.
Objek halaman pendaftaran
Objek halaman pendaftaran yang ditemukan dalam indeks pendaftaran memiliki properti berikut:
| Nama | Tipe | Diperlukan | Catatan |
|---|---|---|---|
| @id | string | yes | URL ke halaman pendaftaran |
| jumlah | Integer | yes | Jumlah pendaftaran yang tersisa di halaman |
| item | array objek | no | Array daun pendaftaran dan metadata asosiasinya |
| lower | string | yes | Versi SemVer 2.0.0 terendah di halaman (inklusif) |
| induk | string | no | URL ke indeks pendaftaran |
| upper | string | yes | Versi SemVer 2.0.0 tertinggi di halaman (inklusif) |
Batas lower dan upper objek halaman berguna ketika metadata untuk versi halaman tertentu diperlukan.
Batas ini dapat digunakan untuk mengambil satu-satunya halaman pendaftaran yang diperlukan. String versi mematuhi aturan versi NuGet. String versi dinormalisasi dan tidak menyertakan metadata build. Seperti semua versi dalam ekosistem NuGet, perbandingan string versi diimplementasikan menggunakan aturan prioritas versi SemVer 2.0.0.
Properti parent hanya akan muncul jika objek halaman pendaftaran memiliki items properti .
items Jika properti tidak ada di objek halaman pendaftaran, URL yang ditentukan dalam @id harus digunakan untuk mengambil metadata tentang versi paket individual. Array items terkadang dikecualikan dari objek halaman sebagai pengoptimalan. Jika jumlah versi ID paket tunggal sangat besar, maka dokumen indeks pendaftaran akan sangat besar dan boros untuk diproses untuk klien yang hanya peduli dengan versi tertentu atau berbagai versi kecil.
Perhatikan bahwa jika items properti ada, @id properti tidak perlu digunakan, karena semua data halaman sudah di-inlin di items properti .
Setiap item dalam array objek items halaman adalah objek JSON yang mewakili daun pendaftaran dan metadata terkait.
Objek daun pendaftaran di halaman
Objek daun pendaftaran yang ditemukan di halaman pendaftaran memiliki properti berikut:
| Nama | Tipe | Diperlukan | Catatan |
|---|---|---|---|
| @id | string | yes | URL ke daun pendaftaran |
| catalogEntry | object | yes | Entri katalog yang berisi metadata paket |
| packageContent | string | yes | URL ke konten paket (.nupkg) |
Setiap objek daun pendaftaran mewakili data yang terkait dengan versi paket tunggal.
Entri katalog
catalogEntry Properti di objek daun pendaftaran memiliki properti berikut:
| Nama | Tipe | Diperlukan | Catatan |
|---|---|---|---|
| @id | string | yes | URL ke dokumen yang digunakan untuk menghasilkan objek ini |
| penulis | string atau array string | no | |
| dependencyGroups | array objek | no | Dependensi paket, dikelompokkan menurut kerangka kerja target |
| penghentian | object | no | Penghentian yang terkait dengan paket |
| description | string | no | |
| iconUrl | string | no | |
| id | string | yes | ID paket |
| bahasa | string | no | |
| licenseUrl | string | no | |
| licenseExpression | string | no | |
| terdaftar | Boolean | no | Harus dianggap sebagai tercantum jika tidak ada |
| minClientVersion | string | no | |
| packageContent | string | no | Duplikat properti yang sama dalam objek induk, hanya disertakan karena alasan warisan |
| projectUrl | string | no | |
| Diterbitkan | string | no | String yang berisi tanda waktu ISO 8601 saat paket diterbitkan |
| readmeUrl | string | no | URL untuk tampilan yang dirender (halaman web HTML) dari paket README |
| requireLicenseAcceptance | Boolean | no | |
| ringkasan | string | no | |
| tag | string atau array string | no | |
| title | string | no | |
| versi | string | yes | String versi lengkap setelah normalisasi |
| kerentanan | array objek | no | Kerentanan keamanan paket |
Properti paket version adalah string versi lengkap setelah normalisasi. Ini berarti bahwa data build SemVer 2.0.0 dapat disertakan di sini.
Properti dependencyGroups adalah array objek yang mewakili dependensi paket, dikelompokkan menurut kerangka kerja target. Jika paket tidak memiliki dependensi, dependencyGroups properti hilang, array kosong, atau dependencies properti semua grup kosong atau hilang.
Nilai licenseExpression properti mematuhi sintaks ekspresi lisensi NuGet.
Catatan
Pada nuget.org, published nilai diatur ke tahun 1900 ketika paket tidak dilisensikan.
Grup dependensi paket
Setiap objek grup dependensi memiliki properti berikut:
| Nama | Tipe | Diperlukan | Catatan |
|---|---|---|---|
| targetFramework | string | no | Kerangka kerja target yang berlaku untuk dependensi ini |
| dependensi | array objek | no |
String targetFramework menggunakan format yang diimplementasikan oleh pustaka .NET NuGet NuGet NuGet.Frameworks. Jika tidak targetFramework ada yang ditentukan, grup dependensi berlaku untuk semua kerangka kerja target.
Properti dependencies adalah array objek, masing-masing mewakili dependensi paket dari paket saat ini.
Dependensi paket
Setiap dependensi paket memiliki properti berikut:
| Nama | Tipe | Diperlukan | Catatan |
|---|---|---|---|
| id | string | yes | ID dependensi paket |
| rentang | object | no | Rentang versi dependensi yang diizinkan |
| registrasi | string | no | URL ke indeks pendaftaran untuk dependensi ini |
range Jika properti dikecualikan atau string kosong, klien harus default ke rentang (, )versi . Artinya, versi dependensi apa pun diizinkan. Nilai * tidak diperbolehkan untuk range properti .
Penghentian paket
Setiap penghentian paket memiliki properti berikut:
| Nama | Tipe | Diperlukan | Catatan |
|---|---|---|---|
| Alasan | array string | yes | Alasan mengapa paket tidak digunakan lagi |
| pesan | string | no | Detail tambahan tentang penghentian ini |
| alternatePackage | object | no | Paket alternatif yang harus digunakan sebagai gantinya |
Properti reasons harus berisi setidaknya satu string dan hanya boleh berisi string dari tabel berikut:
| Alasan | Deskripsi |
|---|---|
| Warisan | Paket tidak lagi dipertahankan |
| CriticalBugs | Paket memiliki bug yang membuatnya tidak cocok untuk penggunaan |
| Lainnya | Paket tidak digunakan lagi karena alasan tidak ada dalam daftar ini |
reasons Jika properti berisi string yang bukan dari set yang diketahui, properti tersebut harus diabaikan. String tidak peka huruf besar/kecil, jadi legacy harus diperlakukan sama dengan Legacy. Tidak ada batasan pengurutan pada array, sehingga string dapat diatur dalam urutan arbitrer apa pun. Selain itu, jika properti hanya berisi string yang bukan dari set yang diketahui, properti harus diperlakukan seolah-olah hanya berisi string "Lainnya".
Paket alternatif
Objek paket alternatif memiliki properti berikut:
| Nama | Tipe | Diperlukan | Catatan |
|---|---|---|---|
| id | string | yes | ID paket alternatif |
| rentang | object | no | Rentang versi yang diizinkan, atau * jika ada versi yang diizinkan |
Kerentanan
Array vulnerability objek. Setiap kerentanan memiliki properti berikut:
| Nama | Tipe | Diperlukan | Catatan |
|---|---|---|---|
| advisoryUrl | string | yes | Lokasi saran keamanan untuk paket |
| keparahan | string | yes | Tingkat keparahan saran: "0" = Rendah, "1" = Sedang, "2" = Tinggi, "3" = Kritis |
Permintaan sampel
GET https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json
Pastikan untuk mengambil URL dasar (https://api.nuget.org/v3/registration-sample/ dalam sampel ini) dari indeks layanan seperti yang disebutkan di bagian URL dasar.
Respon sampel
{
"count": 1,
"items": [
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json#page/3.0.0-beta/3.0.0-beta",
"count": 1,
"items": [
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/3.0.0-beta.json",
"catalogEntry": {
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json",
"authors": ".NET Foundation",
"dependencyGroups": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup",
"dependencies": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup/nuget.core",
"id": "NuGet.Core",
"range": "[2.14.0, )",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.core/index.json"
}
]
}
],
"description": "Core library for creating a Web Application used to host a simple NuGet feed",
"iconUrl": "",
"id": "NuGet.Server.Core",
"language": "",
"licenseUrl": "https://raw.githubusercontent.com/NuGet/NuGet.Server/dev/LICENSE.txt",
"listed": true,
"minClientVersion": "2.6",
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg",
"projectUrl": "https://github.com/NuGet/NuGet.Server",
"published": "2017-10-05T18:40:32.43+00:00",
"requireLicenseAcceptance": false,
"summary": "",
"tags": [ "" ],
"title": "",
"version": "3.0.0-beta",
"vulnerabilities": [
{
"advisoryUrl": "https://github.com/advisories/ABCD-1234-5678-9012",
"severity": "2"
}
]
},
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json"
}
],
"lower": "3.0.0-beta",
"upper": "3.0.0-beta"
}
]
}
Dalam kasus khusus ini, indeks pendaftaran memiliki halaman pendaftaran yang di-inlin sehingga tidak ada permintaan tambahan yang diperlukan untuk mengambil metadata tentang versi paket individual.
Halaman pendaftaran
Halaman pendaftaran berisi daun pendaftaran. URL untuk mengambil halaman pendaftaran ditentukan oleh @id properti di objek halaman pendaftaran yang disebutkan di atas. URL tidak dimaksudkan untuk dapat diprediksi dan harus selalu ditemukan dengan cara dokumen indeks.
Peringatan
Pada nuget.org, URL untuk dokumen halaman pendaftaran secara kebetulan berisi batas bawah dan atas halaman. Namun asumsi ini tidak boleh dibuat oleh klien karena implementasi server bebas untuk mengubah bentuk URL selama dokumen indeks memiliki tautan yang valid.
items Ketika array tidak disediakan dalam indeks pendaftaran, permintaan HTTP GET dari @id nilai akan mengembalikan dokumen JSON yang memiliki objek sebagai akarnya. Objek memiliki properti berikut:
| Nama | Tipe | Diperlukan | Catatan |
|---|---|---|---|
| @id | string | yes | URL ke halaman pendaftaran |
| jumlah | Integer | yes | Jumlah pendaftaran yang tersisa di halaman |
| item | array objek | yes | Array daun pendaftaran dan metadata asosiasinya |
| lower | string | yes | Versi SemVer 2.0.0 terendah di halaman (inklusif) |
| induk | string | yes | URL ke indeks pendaftaran |
| upper | string | yes | Versi SemVer 2.0.0 tertinggi di halaman (inklusif) |
Bentuk objek daun pendaftaran sama seperti pada indeks pendaftaran di atas.
Permintaan sampel
GET https://api.nuget.org/v3/registration-sample/ravendb.client/page/1.0.531/1.0.729-unstable.json
Pastikan untuk mengambil URL dasar (https://api.nuget.org/v3/registration-sample/ dalam sampel ini) dari indeks layanan seperti yang disebutkan di bagian URL dasar.
Respon sampel
{
"count": 2,
"lower": "1.0.531",
"parent": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json",
"upper": "1.0.729-unstable",
"items": [
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.531.json",
"@type": "Package",
"commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1",
"commitTimeStamp": "2017-10-26T14:12:19.3439088Z",
"catalogEntry": {
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.38.37/nuget.protocol.v3.example.1.0.531.json",
"@type": "PackageDetails",
"authors": "NuGet.org Team",
"iconUrl": "https://www.nuget.org/Content/gallery/img/default-package-icon.svg",
"id": "NuGet.Protocol.V3.Example",
"licenseUrl": "http://www.opensource.org/licenses/ms-pl",
"listed": false,
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg",
"projectUrl": "https://github.com/NuGet/NuGetGallery",
"published": "1900-01-01T00:00:00+00:00",
"requireLicenseAcceptance": true,
"title": "NuGet V3 Protocol Example",
"version": "1.0.531"
},
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json"
},
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.729-unstable.json",
"@type": "Package",
"commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1",
"commitTimeStamp": "2017-10-26T14:12:19.3439088Z",
"catalogEntry": {
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.18.22.05/nuget.protocol.v3.example.1.0.729-unstable.json",
"@type": "PackageDetails",
"authors": "NuGet.org Team",
"deprecation": {
"reasons": [
"CriticalBugs"
],
"message": "This package is unstable and broken!",
"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",
"licenseUrl": "http://www.opensource.org/licenses/ms-pl",
"listed": false,
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg",
"projectUrl": "https://github.com/NuGet/NuGetGallery",
"published": "1900-01-01T00:00:00+00:00",
"requireLicenseAcceptance": true,
"summary": "This package is an example for the V3 protocol.",
"title": "NuGet V3 Protocol Example",
"version": "1.0.729-Unstable"
},
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json"
}
]
}
Daun pendaftaran
Daun pendaftaran berisi informasi tentang ID dan versi paket tertentu. Metadata tentang versi tertentu mungkin tidak tersedia dalam dokumen ini. Metadata paket harus diambil dari indeks pendaftaran atau halaman pendaftaran (yang ditemukan menggunakan indeks pendaftaran).
URL untuk mengambil daun pendaftaran diperoleh dari @id properti objek daun pendaftaran baik di indeks pendaftaran atau halaman pendaftaran. Seperti halnya dokumen halaman. URL tidak dimaksudkan untuk dapat diprediksi dan harus selalu ditemukan dengan cara objek halaman pendaftaran.
Peringatan
Pada nuget.org, URL untuk dokumen daun pendaftaran secara kebetulan berisi versi paket. Namun asumsi ini tidak boleh dibuat oleh klien karena implementasi server bebas untuk mengubah bentuk URL selama dokumen induk memiliki tautan yang valid.
Daun pendaftaran adalah dokumen JSON dengan objek akar dengan properti berikut:
| Nama | Tipe | Diperlukan | Catatan |
|---|---|---|---|
| @id | string | yes | URL ke daun pendaftaran |
| catalogEntry | string | no | URL ke entri katalog yang menghasilkan daun ini |
| terdaftar | Boolean | no | Harus dianggap sebagai tercantum jika tidak ada |
| packageContent | string | no | URL ke konten paket (.nupkg) |
| Diterbitkan | string | no | String yang berisi tanda waktu ISO 8601 saat paket diterbitkan |
| registrasi | string | no | URL ke indeks pendaftaran |
Catatan
Pada nuget.org, published nilai diatur ke tahun 1900 ketika paket tidak dilisensikan.
Permintaan sampel
GET https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json
Pastikan untuk mengambil URL dasar (https://api.nuget.org/v3/registration-sample/ dalam sampel ini) dari indeks layanan seperti yang disebutkan di bagian URL dasar.
Respon sampel
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json",
"catalogEntry": "https://api.nuget.org/v3/catalog0/data/2017.08.11.18.24.22/nuget.versioning.4.3.0.json",
"listed": true,
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.versioning/4.3.0/nuget.versioning.4.3.0.nupkg",
"published": "2017-08-11T18:24:14.36+00:00",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.json"
}
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk