NuGet Server API

NuGet Server API'si paketleri indirmek, meta verileri getirmek, yeni paketler yayımlamak ve resmi NuGet istemcilerinde kullanılabilen diğer işlemlerin çoğunu gerçekleştirmek için kullanılabilecek bir HTTP uç noktaları kümesidir.

Bu API, Visual Studio, nuget.exe ve .NET CLI'daki NuGet istemcisi tarafından, Visual Studio kullanıcı arabiriminde arama ve nuget.exe pushgibi dotnet restoreNuGet işlemlerini gerçekleştirmek için kullanılır.

Bazı durumlarda, nuget.org diğer paket kaynakları tarafından uygulanmayan ek gereksinimlere sahip olduğunu unutmayın. Bu farklar nuget.org Protokolleri tarafından belgelenmiştir.

Kullanılabilir nuget.exe sürümlerinin basit bir numaralandırması ve indirilmesi için bkz . tools.json uç noktası.

NuGet paket deposu uyguluyorsanız ek gereksinimler ve öneriler için uygulama kılavuzuna da bakın.

Hizmet dizini

API'nin giriş noktası, iyi bilinen bir konumdaki bir JSON belgesidir. Bu belgeye hizmet dizini adı verilir. nuget.org için hizmet dizininin konumu şeklindedir https://api.nuget.org/v3/index.json.

Bu JSON belgesi, farklı işlevler sağlayan ve farklı kullanım örneklerini karşılayan kaynakların listesini içerir.

API'yi destekleyen istemciler, ilgili paket kaynaklarına bağlanma aracı olarak bu hizmet dizini URL'lerinden birini veya daha fazlasını kabul etmelidir.

Hizmet dizini hakkında daha fazla bilgi için api başvurusuna bakın.

Sürüm oluşturma

API, NuGet'in HTTP protokolünün 3. sürümüdür. Bu protokol bazen "V3 API" olarak adlandırılır. Bu başvuru belgeleri, protokolün bu sürümünü yalnızca "API" olarak adlandıracaktır.

Hizmet dizini şema sürümü, hizmet dizinindeki özelliğiyle version gösterilir. API, sürüm dizesinin ana sürüm numarasına sahip olması zorunlu kılınmıştır 3. Hizmet dizini şemasında hataya neden olmayan değişiklikler yapıldığından, sürüm dizesinin ikincil sürümü artırılır.

Eski istemciler (nuget.exe 2.x gibi) V3 API'sini desteklemez ve yalnızca burada belgelenmemiş olan eski V2 API'sini destekler.

NuGet V3 API'sinin adı, resmi NuGet istemcisinin 2.x sürümü tarafından uygulanan OData tabanlı protokol olan V2 API'sinin ardılı olmasıdır. V3 API'si ilk olarak resmi NuGet istemcisinin 3.0 sürümü tarafından desteklenmiştir ve yine de NuGet istemcisi, 4.0 ve üzerinde tarafından desteklenen en son ana protokol sürümüdür.

API'de ilk kullanıma sunulduğundan bu yana hataya neden olmayan protokol değişiklikleri yapılmıştır.

Kaynaklar ve şema

Hizmet dizini çeşitli kaynakları açıklar. Desteklenen geçerli kaynak kümesi aşağıdaki gibidir:

Kaynak adı	Zorunlu	Açıklama
Katalog	hayır	Tüm paket olaylarının tam kaydı.
PackageBaseAddress	evet	Paket içeriğini (.nupkg) alın.
PackageDetailsUriTemplate	hayır	Paket ayrıntıları web sayfasına erişmek için bir URL oluşturma.
PackagePublish	evet	Paketleri gönderme ve silme (veya listeden kaldırma).
RegistrationsBaseUrl	evet	Paket meta verilerini alma.
ReportAbuseUriTemplate	hayır	Rapor kötüye kullanımı web sayfasına erişmek için URL oluşturma.
RepositorySignatures	hayır	Depo imzalama için kullanılan sertifikaları alma.
SearchAutocompleteService	hayır	Alt dize kullanarak paket kimliklerini ve sürümlerini keşfedin.
SearchQueryService	evet	Paketleri anahtar sözcüklere göre filtreleyin ve arayın.
SymbolPackagePublish	hayır	Sembol paketlerini gönderme.
VulnerabilityInfo	hayır	Bilinen güvenlik açıklarına sahip paketler.

Genel olarak, bir API kaynağı tarafından döndürülen ikili olmayan tüm veriler JSON kullanılarak serileştirilir. Hizmet dizinindeki her kaynak tarafından döndürülen yanıt şeması, bu kaynak için ayrı ayrı tanımlanır. Her kaynak hakkında daha fazla bilgi için yukarıda listelenen konulara bakın.

Gelecekte protokol geliştikçe JSON yanıtlarına yeni özellikler eklenebilir. İstemcinin geleceğe dayanıklı olması için, uygulama yanıt şemasının son olduğunu ve ek veri içeremeyeceğini varsaymamalıdır. Uygulamanın anlamadığı tüm özellikler yoksayılmalıdır.

Not

Bir kaynak herhangi bir otomatik tamamlama davranışı uygulamadığında SearchAutocompleteService düzgün bir şekilde devre dışı bırakılmalıdır. UygulanmadığındaReportAbuseUriTemplate, resmi NuGet istemcisi nuget.org'un uygunsuz kullanım raporu URL'sine geri döner (NuGet/Home#4924 tarafından izlenir). Diğer istemciler, kullanıcıya bir uygunsuz rapor URL'si göstermemeye çalışabilir.

nuget.org üzerinde belgelenmemiş kaynaklar

nuget.org üzerindeki V3 hizmet dizini, yukarıda belgelenmemiş bazı kaynaklara sahiptir. Bir kaynağı belgelememenin birkaç nedeni vardır.

İlk olarak, nuget.org uygulama ayrıntıları olarak kullanılan kaynakları belgelemiyoruz. bu SearchGalleryQueryService kategoriye girer. NuGetGallery , veritabanını kullanmak yerine bazı V2 (OData) sorgularını arama dizinimize temsilci olarak atamak için bu kaynağı kullanır. Bu kaynak ölçeklenebilirlik nedeniyle kullanıma sunulmuştur ve dış kullanıma yönelik değildir.

İkincisi, resmi istemcinin RTM sürümünde hiç gönderilmemiş kaynakları belgelemiyoruz. PackageDisplayMetadataUriTemplate ve PackageVersionDisplayMetadataUriTemplate bu kategoriye girin.

Üçüncü olarak, kasıtlı olarak belgelenmemiş olan V2 protokolüyle sıkı bir şekilde birleştirilmiş kaynakları belgelemiyoruz. Kaynak LegacyGallery bu kategoriye girer. Bu kaynak, V3 hizmet dizininin ilgili V2 kaynak URL'sini işaret etmesini sağlar. Bu kaynak destekler nuget.exe list.

Burada bir kaynak belgelenmemişse, bunlara bağımlılık almamanızı kesinlikle öneririz. Bu belgelenmemiş kaynakların davranışını kaldırabilir veya değiştirebiliriz; bu da uygulamanızı beklenmeyen yollarla bozabilir.

Zaman damgaları

API tarafından döndürülen tüm zaman damgaları UTC'dir veya ISO 8601 gösterimi kullanılarak başka bir şekilde belirtilir.

HTTP yöntemleri

Fiil	Kullanma
GET	Salt okunur bir işlem gerçekleştirir ve genellikle verileri alır.
HEAD	İlgili GET istek için yanıt üst bilgilerini getirir.
PUT	Var olmayan bir kaynak oluşturur veya varsa, bu kaynağı güncelleştirir. Bazı kaynaklar güncelleştirmeyi desteklemeyebilir.
SİL	Bir kaynağı siler veya listeden çıkar.

HTTP durum kodu

Kod	Description
200	Başarılı ve bir yanıt gövdesi var.
201	Başarılı oldu ve kaynak oluşturuldu.
202	Başarılı, istek kabul edildi, ancak bazı çalışmalar hala tamamlanmamış ve zaman uyumsuz olarak tamamlanabilir.
204	Başarılı, ancak yanıt gövdesi yok.
301	Kalıcı bir yeniden yönlendirme.
302	Geçici bir yeniden yönlendirme.
400	URL'deki veya istek gövdesindeki parametreler geçerli değil.
Kategori 401	Sağlanan kimlik bilgileri geçersiz.
Kategori 403	Sağlanan kimlik bilgilerine göre eyleme izin verilmez.
404	İstenen kaynak yok.
409	İstek mevcut bir kaynakla çakişer.
500	Hizmet beklenmeyen bir hatayla karşılaştı.
503	Hizmet geçici olarak kullanılamıyor.

API uç noktasına yapılan tüm GET istekler HTTP yeniden yönlendirmesi (301 veya 302) döndürebilir. İstemciler üst bilgiyi gözlemleyerek Location ve izleyen GETbir vererek bu tür yeniden yönlendirmeleri düzgün bir şekilde işlemelidir. Belirli uç noktalarla ilgili belgeler, yeniden yönlendirmelerin nerede kullanılabileceğini açıkça belirtmez.

500 düzeyinde bir durum kodu söz konusu olduğunda, istemci makul bir yeniden deneme mekanizması uygulayabilir. Resmi NuGet istemcisi, 500 düzeyinde bir durum kodu veya TCP/DNS hatasıyla karşılaştığında üç kez yeniden denenir.

HTTP isteği üstbilgileri

Veri Akışı Adı	Açıklama
X-NuGet-ApiKey	Gönderme ve silme için gereklidir, bkz. PackagePublish kaynak
X-NuGet-İstemci Sürümü	Kullanım dışı bırakıldı ve şununla değiştirildi: X-NuGet-Protocol-Version
X-NuGet-Protocol-Version	Yalnızca nuget.org bazı durumlarda gereklidir, bkz. nuget.org protokolleri
X-NuGet-Session-Id	İsteğe bağlı. NuGet istemcileri v4.7+ aynı NuGet istemci oturumunun parçası olan HTTP isteklerini tanımlar.

içindeki X-NuGet-Session-Id tek bir geri yüklemeyle ilgili tüm işlemler için tek bir değere PackageReferencesahiptir. Otomatik tamamlama ve packages.config geri yükleme gibi diğer senaryolarda, kodun nasıl faktöre dönüştürülmesi nedeniyle birkaç farklı oturum kimliği olabilir.

Kimlik Doğrulaması

Kimlik doğrulaması, tanımlanacağı paket kaynağı uygulamasına bırakılır. nuget.org için yalnızca PackagePublish kaynak, özel bir API anahtarı üst bilgisi aracılığıyla kimlik doğrulaması gerektirir. Ayrıntılar için kaynağa bakınPackagePublish.