Przeczytaj w języku angielskim

Udostępnij za pośrednictwem


Interfejs API serwera NuGet

Interfejs API serwera NuGet to zestaw punktów końcowych HTTP, które mogą służyć do pobierania pakietów, pobierania metadanych, publikowania nowych pakietów i wykonywania większości innych operacji dostępnych w oficjalnych klientach NuGet.

Ten interfejs API jest używany przez klienta NuGet w programie Visual Studio, nuget.exe i interfejsie wiersza polecenia platformy .NET do wykonywania operacji NuGet, takich jak dotnet restore, wyszukiwanie w interfejsie użytkownika programu Visual Studio i nuget.exe push.

Należy pamiętać, że w niektórych przypadkach nuget.org ma dodatkowe wymagania, które nie są wymuszane przez inne źródła pakietów. Te różnice są udokumentowane przez protokoły nuget.org.

Aby uzyskać proste wyliczenie i pobieranie dostępnych wersji nuget.exe, zobacz punkt końcowy tools.json .

Jeśli implementujesz repozytorium pakietów NuGet, zapoznaj się również z przewodnikiem implementacji, aby uzyskać dodatkowe wymagania i zalecenia.

Indeks usług

Punktem wejścia interfejsu API jest dokument JSON w dobrze znanej lokalizacji. Ten dokument jest nazywany indeksem usługi. Lokalizacja indeksu usługi dla nuget.org to https://api.nuget.org/v3/index.json.

Ten dokument JSON zawiera listę zasobów , które zapewniają różne funkcje i spełniają różne przypadki użycia.

Klienci, którzy obsługują interfejs API, powinni zaakceptować co najmniej jeden z tych adresów URL indeksu usługi jako sposób nawiązywania połączenia z odpowiednimi źródłami pakietów.

Aby uzyskać więcej informacji na temat indeksu usługi, zobacz dokumentację interfejsu API.

Wersje

Interfejs API jest w wersji 3 protokołu HTTP nuGet. Ten protokół jest czasami nazywany "interfejsem API w wersji 3". Te dokumenty referencyjne będą odwoływać się do tej wersji protokołu po prostu jako "interfejs API".

Wersja schematu indeksu usługi jest wskazywana przez version właściwość w indeksie usługi. Interfejs API nakazuje, aby ciąg wersji miał numer wersji głównej .3 W miarę wprowadzania zmian powodujących niezgodność w schemacie indeksu usługi wersja pomocnicza ciągu wersji zostanie zwiększona.

Starsi klienci (na przykład nuget.exe 2.x) nie obsługują interfejsu API w wersji 3 i obsługują tylko starszy interfejs API w wersji 2, który nie został opisany w tym miejscu.

Interfejs API NuGet v3 jest nazwany jako taki, ponieważ jest następcą interfejsu API w wersji 2, który był protokołem opartym na protokole OData zaimplementowanym przez wersję 2.x oficjalnego klienta NuGet. Interfejs API w wersji 3 został po raz pierwszy obsługiwany przez wersję 3.0 oficjalnego klienta NuGet i jest nadal najnowszą główną wersją protokołu obsługiwaną przez klienta NuGet, 4.0 i nowszego.

Zmiany protokołu powodujące niezgodność zostały wprowadzone w interfejsie API od czasu jej pierwszego wydania.

Zasoby i schemat

Indeks usługi opisuje różne zasoby. Bieżący zestaw obsługiwanych zasobów jest następujący:

Nazwa zasobu Wymagania opis
Katalog nie Pełny rekord wszystkich zdarzeń pakietu.
PackageBaseAddress tak Pobierz zawartość pakietu (nupkg).
PackageDetailsUriTemplate nie Konstruowanie adresu URL w celu uzyskania dostępu do strony sieci Web szczegółów pakietu.
PackagePublish tak Wypychanie i usuwanie (lub usuwanie) pakietów.
RejestracjeBaseUrl tak Pobieranie metadanych pakietu.
ReportAbuseUriTemplate nie Skonstruuj adres URL umożliwiający dostęp do strony internetowej nadużyć w raporcie.
RepositorySignatures nie Pobierz certyfikaty używane do podpisywania repozytorium.
SearchAutocompleteService nie Odnajdź identyfikatory i wersje pakietów według podciągów.
SearchQueryService tak Filtruj i wyszukuj pakiety według słowa kluczowego.
SymbolPackagePublish nie Wypychanie pakietów symboli.
VulnerabilityInfo nie Pakiety ze znanymi lukami w zabezpieczeniach.

Ogólnie rzecz biorąc, wszystkie dane niebinarne zwracane przez zasób interfejsu API są serializowane przy użyciu formatu JSON. Schemat odpowiedzi zwracany przez każdy zasób w indeksie usługi jest definiowany indywidualnie dla tego zasobu. Aby uzyskać więcej informacji na temat każdego zasobu, zobacz tematy wymienione powyżej.

W przyszłości, w miarę rozwoju protokołu, nowe właściwości mogą zostać dodane do odpowiedzi JSON. Aby klient był odporny na przyszłość, implementacja nie powinna zakładać, że schemat odpowiedzi jest końcowy i nie może zawierać dodatkowych danych. Wszystkie właściwości, których implementacja nie rozumie, powinny być ignorowane.

Uwaga

Jeśli źródło nie implementuje SearchAutocompleteService żadnego zachowania autouzupełniania, powinno być bezpiecznie wyłączone. Gdy ReportAbuseUriTemplate nie zostanie zaimplementowany, oficjalny klient NuGet powraca do adresu URL nadużyć raportu nuget.org (śledzony przez NuGet/Home#4924). Inni klienci mogą zdecydować się po prostu nie pokazywać użytkownikowi adresu URL nadużyć w raporcie.

Zasoby nieudokumentowane w usłudze nuget.org

Indeks usługi w wersji 3 nuget.org zawiera pewne zasoby, które nie zostały udokumentowane powyżej. Istnieje kilka powodów, dla których nie można udokumentować zasobu.

Najpierw nie dokumentujemy zasobów używanych jako szczegóły implementacji nuget.org. Należy SearchGalleryQueryService do tej kategorii. Narzędzie NuGetGallery używa tego zasobu do delegowania niektórych zapytań OData (V2) do naszego indeksu wyszukiwania zamiast używania bazy danych. Ten zasób został wprowadzony ze względu na skalowalność i nie jest przeznaczony do użytku zewnętrznego.

Po drugie, nie dokumentujemy zasobów, które nigdy nie zostały wysłane w wersji RTM oficjalnego klienta. PackageDisplayMetadataUriTemplate i PackageVersionDisplayMetadataUriTemplate należy do tej kategorii.

Po trzecie, nie dokumentujemy zasobów ściśle powiązanych z protokołem V2, który jest celowo nieudokumentowany. Zasób LegacyGallery należy do tej kategorii. Ten zasób umożliwia indeksowi usługi w wersji 3 wskazanie odpowiedniego źródłowego adresu URL wersji 2. Ten zasób obsługuje element nuget.exe list.

Jeśli zasób nie jest udokumentowany w tym miejscu, zdecydowanie zalecamy, aby nie brać na nich zależności. Możemy usunąć lub zmienić zachowanie tych nieudokumentowanych zasobów, co może spowodować awarię implementacji w nieoczekiwany sposób.

Znaczniki czasu

Wszystkie znaczniki czasu zwracane przez interfejs API są utc lub w inny sposób określone przy użyciu reprezentacji ISO 8601 .

Metody HTTP

Czasownik Używanie
GET Wykonuje operację tylko do odczytu, zazwyczaj pobiera dane.
HEAD Pobiera nagłówki odpowiedzi dla odpowiedniego GET żądania.
ODŁÓŻ Tworzy zasób, który nie istnieje lub, jeśli istnieje, aktualizuje go. Niektóre zasoby mogą nie obsługiwać aktualizacji.
DELETE Usuwa lub usuwa listę zasobu.

Kody stanu HTTP

Kod opis
200 Powodzenie i istnieje treść odpowiedzi.
201 Powodzenie i utworzono zasób.
202 Żądanie zostało zaakceptowane, ale niektóre prace mogą być nadal niekompletne i ukończone asynchronicznie.
204 Sukces, ale nie ma treści odpowiedzi.
301 Trwałe przekierowanie.
302 Tymczasowe przekierowanie.
400 Parametry w adresie URL lub w treści żądania są nieprawidłowe.
401 Podane poświadczenia są nieprawidłowe.
403 Akcja nie jest dozwolona, biorąc pod uwagę podane poświadczenia.
404 Żądany zasób nie istnieje.
409 Żądanie powoduje konflikt z istniejącym zasobem.
500 Usługa napotkała nieoczekiwany błąd.
503 Usługa jest tymczasowo niedostępna.

Każde GET żądanie skierowane do punktu końcowego interfejsu API może zwrócić przekierowanie HTTP (301 lub 302). Klienci powinni bezpiecznie obsługiwać takie przekierowania, obserwując nagłówek i wydając Location kolejne GET. Dokumentacja dotycząca określonych punktów końcowych nie będzie jawnie określać, gdzie mogą być używane przekierowania.

W przypadku kodu stanu na poziomie 500 klient może zaimplementować rozsądny mechanizm ponawiania prób. Oficjalny klient NuGet ponawia próbę trzy razy podczas napotkania dowolnego kodu stanu na poziomie 500 lub błędu TCP/DNS.

Nagłówki żądań HTTP

Nazwa/nazwisko opis
X-NuGet-ApiKey Wymagane do wypychania i usuwania, zobacz PackagePublish zasób
X-NuGet-Client-Version Przestarzałe i zastąpione przez X-NuGet-Protocol-Version
X-NuGet-Protocol-Version Wymagane w niektórych przypadkach tylko w nuget.org, zobacz protokoły nuget.org
X-NuGet-Session-Id Opcjonalne. Klienci NuGet w wersji 4.7 lub nowszej identyfikują żądania HTTP będące częścią tej samej sesji klienta NuGet.

Element X-NuGet-Session-Id ma pojedynczą wartość dla wszystkich operacji związanych z pojedynczym przywracaniem w programie PackageReference. W przypadku innych scenariuszy, takich jak autouzupełnianie i packages.config przywracanie, może istnieć kilka różnych identyfikatorów sesji ze względu na faktorowany kod.

Uwierzytelnianie

Uwierzytelnianie jest pozostawione do implementacji źródła pakietu do zdefiniowania. W przypadku nuget.org tylko PackagePublish zasób wymaga uwierzytelniania za pośrednictwem specjalnego nagłówka klucza interfejsu API. Aby uzyskać szczegółowe informacje, zobacz PackagePublish zasób .