Baca dalam bahasa Inggris

Bagikan melalui


API Server NuGet

NUGet Server API adalah sekumpulan titik akhir HTTP yang dapat digunakan untuk mengunduh paket, mengambil metadata, menerbitkan paket baru, dan melakukan sebagian besar operasi lain yang tersedia di klien NuGet resmi.

API ini digunakan oleh klien NuGet di Visual Studio, nuget.exe, dan .NET CLI untuk melakukan operasi NuGet seperti dotnet restore, cari di Visual Studio UI, dan nuget.exe push.

Perhatikan dalam beberapa kasus, nuget.org memiliki persyaratan tambahan yang tidak diberlakukan oleh sumber paket lain. Perbedaan ini didokumenkan oleh Protokol nuget.org.

Untuk enumerasi sederhana dan unduhan versi nuget.exe yang tersedia, lihat titik akhir tools.json .

Jika Anda menerapkan repositori paket NuGet, lihat juga panduan implementasi untuk persyaratan dan rekomendasi tambahan.

Indeks layanan

Titik masuk untuk API adalah dokumen JSON di lokasi terkenal. Dokumen ini disebut indeks layanan. Lokasi indeks layanan untuk nuget.org adalah https://api.nuget.org/v3/index.json.

Dokumen JSON ini berisi daftar sumber daya yang menyediakan fungsionalitas yang berbeda dan memenuhi kasus penggunaan yang berbeda.

Klien yang mendukung API harus menerima satu atau beberapa URL indeks layanan ini sebagai sarana untuk menyambungkan ke sumber paket masing-masing.

Untuk informasi selengkapnya tentang indeks layanan, lihat referensi API-nya.

Penerapan versi

API adalah versi 3 dari protokol HTTP NuGet. Protokol ini terkadang disebut sebagai "API V3". Dokumen referensi ini akan merujuk ke versi protokol ini hanya sebagai "API."

Versi skema indeks layanan ditunjukkan oleh version properti dalam indeks layanan. API mengamanatkan bahwa string versi memiliki nomor versi utama .3 Karena perubahan yang tidak melanggar dilakukan pada skema indeks layanan, versi minor string versi akan ditingkatkan.

Klien lama (seperti nuget.exe 2.x) tidak mendukung API V3 dan hanya mendukung API V2 yang lebih lama, yang tidak didokumenkan di sini.

API NuGet V3 dinamai seperti itu karena merupakan penerus API V2, yang merupakan protokol berbasis OData yang diterapkan oleh versi 2.x dari klien NuGet resmi. API V3 pertama kali didukung oleh versi 3.0 dari klien NuGet resmi dan masih merupakan versi protokol utama terbaru yang didukung oleh klien NuGet, 4.0 dan seterangnya.

Perubahan protokol yang tidak melanggar telah dilakukan pada API sejak pertama kali dirilis.

Sumber daya dan skema

Indeks layanan menjelaskan berbagai sumber daya. Kumpulan sumber daya yang didukung saat ini adalah sebagai berikut:

Nama sumber daya Diperlukan Deskripsi
Katalog no Catatan lengkap semua peristiwa paket.
PackageBaseAddress yes Dapatkan konten paket (.nupkg).
PackageDetailsUriTemplate no Buat URL untuk mengakses halaman web detail paket.
PackagePublish yes Dorong dan hapus (atau batalkan daftar) paket.
RegistrationsBaseUrl yes Dapatkan metadata paket.
ReportAbuseUriTemplate no Buat URL untuk mengakses halaman web penyalahgunaan laporan.
RepositoriSignatures no Dapatkan sertifikat yang digunakan untuk penandatanganan repositori.
SearchAutocompleteService no Temukan ID dan versi paket dengan substring.
SearchQueryService yes Filter dan cari paket menurut kata kunci.
SymbolPackagePublish no Mendorong paket simbol.
KerentananInfo no Paket dengan kerentanan yang diketahui.

Secara umum, semua data non-biner yang dikembalikan oleh sumber daya API diserialisasikan menggunakan JSON. Skema respons yang dikembalikan oleh setiap sumber daya dalam indeks layanan didefinisikan secara individual untuk sumber daya tersebut. Untuk informasi selengkapnya tentang setiap sumber daya, lihat topik yang tercantum di atas.

Di masa depan, seiring berkembangnya protokol, properti baru dapat ditambahkan ke respons JSON. Agar klien menjadi bukti masa depan, implementasi tidak boleh berasumsi bahwa skema respons bersifat final dan tidak dapat menyertakan data tambahan. Semua properti yang tidak dipahami implementasi harus diabaikan.

Catatan

Ketika sumber tidak menerapkan SearchAutocompleteService perilaku lengkapi otomatis apa pun harus dinonaktifkan dengan anggun. Ketika ReportAbuseUriTemplate tidak diimplementasikan, klien NuGet resmi kembali ke URL penyalahgunaan laporan nuget.org (dilacak oleh NuGet/Home#4924). Klien lain dapat memilih untuk tidak hanya menampilkan URL penyalahgunaan laporan kepada pengguna.

Sumber daya yang tidak terdokumentasi pada nuget.org

Indeks layanan V3 pada nuget.org memiliki beberapa sumber daya yang tidak didokumenkan di atas. Ada beberapa alasan untuk tidak mendokumenkan sumber daya.

Pertama, kami tidak mendokumentasikan sumber daya yang digunakan sebagai detail implementasi nuget.org. Termasuk SearchGalleryQueryService dalam kategori ini. NuGetGallery menggunakan sumber daya ini untuk mendelegasikan beberapa kueri V2 (OData) ke indeks pencarian kami alih-alih menggunakan database. Sumber daya ini diperkenalkan karena alasan skalabilitas dan tidak ditujukan untuk penggunaan eksternal.

Kedua, kami tidak mendokumentasikan sumber daya yang tidak pernah dikirim dalam versi RTM klien resmi. PackageDisplayMetadataUriTemplate dan PackageVersionDisplayMetadataUriTemplate termasuk dalam kategori ini.

Ketiga, kami tidak mendokumentasikan sumber daya yang digabungkan erat dengan protokol V2, yang sengaja tidak didokumentasikan. Sumber LegacyGallery daya termasuk dalam kategori ini. Sumber daya ini memungkinkan indeks layanan V3 untuk menunjuk ke URL sumber V2 yang sesuai. Sumber daya ini mendukung nuget.exe list.

Jika sumber daya tidak didokumenkan di sini, kami sangat menyarankan agar Anda tidak mengambil dependensi pada sumber daya tersebut. Kami dapat menghapus atau mengubah perilaku sumber daya yang tidak terdokumentasi ini yang dapat merusak implementasi Anda dengan cara yang tidak terduga.

Stempel waktu

Semua tanda waktu yang dikembalikan oleh API adalah UTC atau ditentukan lain menggunakan representasi ISO 8601 .

Metode HTTP

Kata kerja Menggunakan
GET Melakukan operasi baca-saja, biasanya mengambil data.
HEAD Mengambil header respons untuk permintaan yang GET sesuai.
TARUH Membuat sumber daya yang tidak ada atau, jika memang ada, memperbaruinya. Beberapa sumber daya mungkin tidak mendukung pembaruan.
DELETE Menghapus atau membatalkan daftar sumber daya.

Kode status HTTP

Kode Deskripsi
200 Sukses, dan ada isi respons.
201 Berhasil, dan sumber daya dibuat.
202 Berhasil, permintaan telah diterima tetapi beberapa pekerjaan mungkin masih tidak lengkap dan diselesaikan secara asinkron.
204 Sukses, tetapi tidak ada isi respons.
301 Pengalihan permanen.
302 Pengalihan sementara.
400 Parameter dalam URL atau di isi permintaan tidak valid.
401 Kredensial yang disediakan tidak valid.
403 Tindakan tidak diperbolehkan diberikan kredensial yang disediakan.
404 Sumber daya yang diminta tidak ada.
409 Permintaan bertentangan dengan sumber daya yang ada.
500 Layanan mengalami kesalahan tak terduga.
503 Layanan tidak tersedia untuk sementara.

Setiap GET permintaan yang dibuat ke titik akhir API dapat mengembalikan pengalihan HTTP (301 atau 302). Klien harus dengan anggun menangani pengalihan tersebut Location dengan mengamati header dan mengeluarkan GET. Dokumentasi mengenai titik akhir tertentu tidak akan secara eksplisit memanggil di mana pengalihan dapat digunakan.

Dalam kasus kode status tingkat 500, klien dapat menerapkan mekanisme coba lagi yang wajar. Klien NuGet resmi mencoba kembali tiga kali ketika mengalami kode status tingkat 500 atau kesalahan TCP/DNS.

Header permintaan HTTP

Nama Deskripsi
X-NuGet-ApiKey Diperlukan untuk pendorongan dan penghapusan, lihat PackagePublish sumber daya
X-NuGet-Client-Version Tidak digunakan lagi dan digantikan oleh X-NuGet-Protocol-Version
X-NuGet-Protocol-Version Diperlukan dalam kasus tertentu hanya pada nuget.org, lihat protokol nuget.org
X-NuGet-Session-Id Opsional. Klien NuGet v4.7+ mengidentifikasi permintaan HTTP yang merupakan bagian dari sesi klien NuGet yang sama.

X-NuGet-Session-Id memiliki nilai tunggal untuk semua operasi yang terkait dengan satu pemulihan di PackageReference. Untuk skenario lain seperti pelengkapan otomatis dan packages.config pemulihan mungkin ada beberapa ID sesi yang berbeda karena bagaimana kode diperhitungkan.

Autentikasi

Autentikasi dibiarkan hingga implementasi sumber paket untuk ditentukan. Untuk nuget.org, hanya sumber daya yang PackagePublish memerlukan autentikasi melalui header kunci API khusus. Lihat PackagePublish sumber daya untuk detailnya.