API Server NuGet
L'API del server NuGet è un set di endpoint HTTP che possono essere usati per scaricare pacchetti, recuperare metadati, pubblicare nuovi pacchetti ed eseguire la maggior parte delle altre operazioni disponibili nei client NuGet ufficiali.
Questa API viene usata dal client NuGet in Visual Studio, nuget.exe e dall'interfaccia della riga di comando di .NET per eseguire operazioni NuGet, dotnet restore
ad esempio , eseguire ricerche nell'interfaccia utente di Visual Studio e nuget.exe push
.
Si noti che in alcuni casi nuget.org presenta requisiti aggiuntivi non applicati da altre origini del pacchetto. Queste differenze sono documentate dai protocolli di nuget.org.
Per un'enumerazione semplice e il download delle versioni di nuget.exe disponibili, vedere l'endpoint tools.json .
Se si implementa un repository di pacchetti NuGet, vedere anche la guida all'implementazione per altri requisiti e consigli.
Il punto di ingresso per l'API è un documento JSON in una posizione nota. Questo documento è denominato indice del servizio. La posizione dell'indice del servizio per nuget.org è https://api.nuget.org/v3/index.json
.
Questo documento JSON contiene un elenco di risorse che forniscono funzionalità diverse e soddisfano casi d'uso diversi.
I client che supportano l'API devono accettare uno o più di questi URL di indice del servizio come mezzo per connettersi alle rispettive origini del pacchetto.
Per altre informazioni sull'indice del servizio, vedere le informazioni di riferimento sulle API.
L'API è la versione 3 del protocollo HTTP di NuGet. Questo protocollo viene talvolta definito "API V3". Questi documenti di riferimento fanno riferimento a questa versione del protocollo semplicemente come "l'API".
La versione dello schema dell'indice del servizio è indicata dalla version
proprietà nell'indice del servizio. L'API impone che la stringa di versione abbia un numero di versione principale di 3
. Man mano che vengono apportate modifiche non di rilievo allo schema dell'indice del servizio, la versione secondaria della stringa di versione verrà aumentata.
I client meno recenti (ad esempio nuget.exe 2.x) non supportano l'API V3 e supportano solo l'API V2 precedente, non documentata qui.
L'API NuGet V3 è denominata come tale perché è il successore dell'API V2, che era il protocollo basato su OData implementato dalla versione 2.x del client NuGet ufficiale. L'API V3 è stata supportata per la prima volta dalla versione 3.0 del client NuGet ufficiale ed è ancora la versione del protocollo principale più recente supportata dal client NuGet, 4.0 e on.
Le modifiche al protocollo non di rilievo sono state apportate all'API dalla prima versione.
L'indice del servizio descrive un'ampia gamma di risorse. Il set corrente di risorse supportate è il seguente:
Nome risorsa | Richiesto | Descrizione |
---|---|---|
Catalog | no | Record completo di tutti gli eventi del pacchetto. |
PackageBaseAddress | yes | Ottenere il contenuto del pacchetto (.nupkg). |
PackageDetailsUriTemplate | no | Creare un URL per accedere a una pagina Web dei dettagli del pacchetto. |
PackagePublish | yes | Eseguire il push e l'eliminazione di pacchetti (o annullare l'elenco). |
RegistrationsBaseUrl | yes | Ottenere i metadati del pacchetto. |
ReportAbuseUriTemplate | no | Creare un URL per accedere a una pagina Web di abuso di report. |
RepositorySignatures | no | Ottenere i certificati usati per la firma del repository. |
SearchAutocompleteService | no | Individuare gli ID e le versioni dei pacchetti tramite sottostringa. |
SearchQueryService | yes | Filtrare e cercare pacchetti per parola chiave. |
SymbolPackagePublish | no | Eseguire il push dei pacchetti di simboli. |
VulnerabilityInfo | no | Pacchetti con vulnerabilità note. |
In generale, tutti i dati non binari restituiti da una risorsa API vengono serializzati tramite JSON. Lo schema di risposta restituito da ogni risorsa nell'indice del servizio viene definito singolarmente per tale risorsa. Per altre informazioni su ogni risorsa, vedere gli argomenti elencati in precedenza.
In futuro, man mano che il protocollo evolve, è possibile aggiungere nuove proprietà alle risposte JSON. Affinché il client sia di prova futura, l'implementazione non deve presupporre che lo schema di risposta sia finale e non possa includere dati aggiuntivi. Tutte le proprietà che l'implementazione non riconosce devono essere ignorate.
Nota
Quando un'origine non implementa SearchAutocompleteService
alcun comportamento di completamento automatico deve essere disabilitato normalmente. Quando ReportAbuseUriTemplate
non viene implementato, il client NuGet ufficiale esegue il fallback all'URL dell'abuso di report di nuget.org (rilevato da NuGet/Home#4924). Altri client possono scegliere di non visualizzare semplicemente un URL di abuso di report per l'utente.
L'indice del servizio V3 in nuget.org include alcune risorse non documentate in precedenza. Esistono alcuni motivi per cui non è possibile documentare una risorsa.
In primo luogo, non vengono documentato le risorse usate come dettaglio di implementazione di nuget.org. Rientra SearchGalleryQueryService
in questa categoria. NuGetGallery usa questa risorsa per delegare alcune query V2 (OData) all'indice di ricerca anziché usare il database. Questa risorsa è stata introdotta per motivi di scalabilità e non è destinata all'uso esterno.
In secondo luogo, non vengono documentate le risorse mai spedite in una versione RTM del client ufficiale.
PackageDisplayMetadataUriTemplate
e PackageVersionDisplayMetadataUriTemplate
rientrano in questa categoria.
In terzo luogo, non vengono documentate le risorse strettamente associate al protocollo V2, che è intenzionalmente non documentato. La LegacyGallery
risorsa rientra in questa categoria. Questa risorsa consente a un indice del servizio V3 di puntare a un URL di origine V2 corrispondente. Questa risorsa supporta .nuget.exe list
Se una risorsa non è documentata qui, è consigliabile non assumerne una dipendenza. È possibile rimuovere o modificare il comportamento di queste risorse non documentate che potrebbero interrompere l'implementazione in modi imprevisti.
Tutti i timestamp restituiti dall'API sono UTC o vengono specificati in altro modo usando la rappresentazione ISO 8601 .
Verbo | Utilizzo |
---|---|
GET | Esegue un'operazione di sola lettura, in genere recuperando i dati. |
HEAD | Recupera le intestazioni di risposta per la richiesta corrispondente GET . |
PUT | Crea una risorsa che non esiste o, se esiste, la aggiorna. Alcune risorse potrebbero non supportare l'aggiornamento. |
DELETE | Elimina o annulla l'elenco di una risorsa. |
Codice | Descrizione |
---|---|
200 | Il successo e c'è un corpo della risposta. |
201 | Operazione riuscita e creazione della risorsa. |
202 | Esito positivo, la richiesta è stata accettata, ma alcune operazioni potrebbero essere ancora incomplete e completate in modo asincrono. |
204 | Il successo, ma non c'è alcun corpo della risposta. |
301 | Reindirizzamento permanente. |
302 | Reindirizzamento temporaneo. |
400 | I parametri nell'URL o nel corpo della richiesta non sono validi. |
401 | Le credenziali specificate non sono valide. |
403 | L'azione non è consentita in base alle credenziali specificate. |
404 | La risorsa richiesta non esiste. |
409 | La richiesta è in conflitto con una risorsa esistente. |
500 | Il servizio ha rilevato un errore imprevisto. |
503 | Il servizio è temporaneamente non disponibile. |
Qualsiasi GET
richiesta effettuata a un endpoint API può restituire un reindirizzamento HTTP (301 o 302). I client devono gestire correttamente tali reindirizzamenti osservando l'intestazione Location
e emettendo un oggetto successivo GET
. La documentazione relativa a endpoint specifici non chiamerà in modo esplicito dove possono essere usati i reindirizzamenti.
Nel caso di un codice di stato a 500 livelli, il client può implementare un meccanismo di ripetizione ragionevole. Il client NuGet ufficiale ritenta tre volte quando viene rilevato un codice di stato a 500 livelli o un errore TCP/DNS.
Nome | Descrizione |
---|---|
X-NuGet-ApiKey | Obbligatorio per il push e l'eliminazione, vedere PackagePublish la risorsa |
X-NuGet-Client-Version | Deprecato e sostituito da X-NuGet-Protocol-Version |
X-NuGet-Protocol-Version | Obbligatorio in alcuni casi solo in nuget.org, vedere protocolli nuget.org |
X-NuGet-Session-Id | Facoltativo. I client NuGet v4.7+ identificano le richieste HTTP che fanno parte della stessa sessione client NuGet. |
ha X-NuGet-Session-Id
un singolo valore per tutte le operazioni correlate a un singolo ripristino in PackageReference
. Per altri scenari, ad esempio il completamento automatico e packages.config
il ripristino, potrebbero essere presenti diversi ID sessione a causa della modalità di factoring del codice.
L'autenticazione viene lasciata all'implementazione dell'origine del pacchetto da definire. Per nuget.org, solo la PackagePublish
risorsa richiede l'autenticazione tramite un'intestazione di chiave API speciale. Per informazioni dettagliate, vedere PackagePublish
la risorsa .