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 push
gibi dotnet restore
NuGet 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.
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.
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.
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 ü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.
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.
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. |
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 GET
bir 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.
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 PackageReference
sahiptir. 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ı, 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
.