Metadata paket

Artikel
03/14/2024

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"
}

Bagikan melalui

Metadata paket

Penerapan versi

RegistrationsBaseUrl

RegistrationsBaseUrl/3.4.0

RegistrationsBaseUrl/3.6.0

URL Dasar

Metode HTTP

Indeks pendaftaran

Halaman pendaftaran dan daun

Parameter permintaan

Respons

Objek halaman pendaftaran

Objek daun pendaftaran di halaman

Entri katalog

Grup dependensi paket

Dependensi paket

Penghentian paket

Paket alternatif

Kerentanan

Permintaan sampel

Respon sampel

Halaman pendaftaran

Permintaan sampel

Respon sampel

Daun pendaftaran

Permintaan sampel

Respon sampel

Saran dan Komentar

Sumber Daya Tambahan: