Metadane pakietu

Istnieje możliwość pobrania metadanych dotyczących pakietów dostępnych w źródle pakietu przy użyciu interfejsu API nuGet w wersji 3. Te metadane można pobrać przy użyciu zasobu znajdującego RegistrationsBaseUrl się w indeksie usługi.

Kolekcja dokumentów znajdujących się w obszarze RegistrationsBaseUrl jest często nazywana "rejestracjami" lub "rejestracjami obiektów blob". Zestaw dokumentów w ramach pojedynczego RegistrationsBaseUrl elementu jest określany jako "gałąź rejestracji". Gałąź rejestracji zawiera metadane dotyczące każdego pakietu dostępnego w źródle pakietu.

Wersje

Używane są następujące @type wartości:

Reprezentuje to trzy odrębne hive rejestracji dostępne dla różnych wersji klienta.

RejestracjeBaseUrl

Te rejestracje nie są kompresowane (co oznacza, że używają implikowanego Content-Encoding: identityelementu ). Pakiety SemVer 2.0.0 są wykluczone z tego elementu hive.

RejestracjeBaseUrl/3.4.0

Te rejestracje są kompresowane przy użyciu polecenia Content-Encoding: gzip. Pakiety SemVer 2.0.0 są wykluczone z tego elementu hive.

RegistrationsBaseUrl/3.6.0

Te rejestracje są kompresowane przy użyciu polecenia Content-Encoding: gzip. Pakiety SemVer 2.0.0 są zawarte w tym hive. Aby uzyskać więcej informacji na temat programu SemVer 2.0.0, zobacz Obsługa protokołu SemVer 2.0.0 dla nuget.org.

Podstawowy adres URL

Podstawowym adresem URL dla następujących interfejsów API jest wartość @id właściwości skojarzonej z wyżej wymienionymi wartościami zasobów @type . W poniższym dokumencie zostanie użyty podstawowy adres URL {@id} symbolu zastępczego. Podstawowy adres URL może ulec zmianie na podstawie implementacji lub zmian infrastruktury w źródle pakietu, dlatego musi być dynamicznie pobierany z indeksu usługi przez oprogramowanie klienckie.

Metody HTTP

Wszystkie adresy URL znalezione w zasobie rejestracji obsługują metody GET HTTP i HEAD.

Indeks rejestracji

Metadane pakietu grup zasobów rejestracji według identyfikatora pakietu. Nie można jednocześnie pobierać danych o więcej niż jednym identyfikatorze pakietu. Ten zasób nie umożliwia odnajdywania identyfikatorów pakietów. Zamiast tego zakłada się, że klient zna już żądany identyfikator pakietu. Dostępne metadane dotyczące każdej wersji pakietu różnią się w zależności od implementacji serwera. Obiekty blob rejestracji pakietu mają następującą strukturę hierarchiczną:

• Indeks: punkt wejścia metadanych pakietu, współużytkowany przez wszystkie pakiety w źródle o tym samym identyfikatorze pakietu.
• Strona: grupowanie wersji pakietów. Liczba wersji pakietów na stronie jest definiowana przez implementację serwera.
• Liść: dokument specyficzny dla pojedynczej wersji pakietu.

Adres URL indeksu rejestracji jest przewidywalny i może być określany przez klienta przy użyciu identyfikatora pakietu i wartości zasobu @id rejestracji z indeksu usługi. Adresy URL stron rejestracji i liści są odnajdywane przez sprawdzenie indeksu rejestracji.

Strony rejestracji i liście

Chociaż implementacja serwera nie jest ściśle wymagana do przechowywania liści rejestracji w oddzielnych dokumentach strony rejestracji, zaleca się oszczędzanie pamięci po stronie klienta. Zamiast oznaczać wszystkie liście rejestracji w indeksie lub natychmiast przechowywać liście w dokumentach strony, zaleca się, aby implementacja serwera zdefiniować niektóre heurystyczne do wyboru między dwoma podejściami na podstawie liczby wersji pakietu lub skumulowanego rozmiaru liści pakietu.

Przechowywanie wszystkich wersji pakietu (liście) w indeksie rejestracji zapisuje liczbę żądań HTTP niezbędnych do pobrania metadanych pakietu, ale oznacza, że należy pobrać większy dokument i przydzielić więcej pamięci klienta. Z drugiej strony, jeśli implementacja serwera natychmiast przechowuje rejestrację w oddzielnych dokumentach strony, klient musi wykonać więcej żądań HTTP, aby uzyskać potrzebne informacje.

Heurystyka używana przez nuget.org jest następująca: jeśli istnieje 128 lub więcej wersji pakietu, podziel liście na strony o rozmiarze 64. Jeśli istnieje mniej niż 128 wersji, wszystkie liście wbudowane do indeksu rejestracji. Należy pamiętać, że oznacza to, że pakiety z wersjami od 65 do 127 będą miały dwie strony w indeksie, ale obie strony zostaną podkreślone.

GET {@id}/{LOWER_ID}/index.json

Parametry żądania

Wartość LOWER_ID jest identyfikatorem żądanego pakietu małymi literami przy użyciu reguł implementowanych przez program . Metoda platformy System.String.ToLowerInvariant() NET.

Response

Odpowiedź to dokument JSON, który ma obiekt główny o następujących właściwościach:

Każdy element w tablicy obiektu indeksu items jest obiektem JSON reprezentującym stronę rejestracji.

Obiekt strony rejestracji

Obiekt strony rejestracji znajdujący się w indeksie rejestracji ma następujące właściwości:

Granice lower obiektu strony i upper są przydatne, gdy potrzebne są metadane dla określonej wersji strony. Te granice mogą służyć do pobierania tylko wymaganej strony rejestracji. Ciągi wersji są zgodne z regułami wersji pakietu NuGet. Ciągi wersji są znormalizowane i nie zawierają metadanych kompilacji. Podobnie jak w przypadku wszystkich wersji w ekosystemie NuGet, porównanie ciągów wersji jest implementowane przy użyciu reguł pierwszeństwa wersji SemVer 2.0.0.

Właściwość będzie wyświetlana parent tylko wtedy, gdy obiekt strony rejestracji ma items właściwość .

items Jeśli właściwość nie istnieje w obiekcie strony rejestracji, adres URL określony w elemecie @id musi służyć do pobierania metadanych dotyczących poszczególnych wersji pakietu. Tablica items jest czasami wykluczana z obiektu strony jako optymalizacji. Jeśli liczba wersji pojedynczego identyfikatora pakietu jest bardzo duża, dokument indeksu rejestracji będzie ogromny i marnotrawny do przetworzenia dla klienta, który dba tylko o określoną wersję lub mały zakres wersji.

Należy pamiętać, że jeśli items właściwość jest obecna, @id właściwość nie musi być używana, ponieważ wszystkie dane strony są już wbudowane we items właściwości .

Każdy element w tablicy items obiektu strony jest obiektem JSON reprezentującym liść rejestracji i skojarzonymi metadanymi.

Obiekt liścia rejestracji na stronie

Obiekt liścia rejestracji znajdujący się na stronie rejestracji ma następujące właściwości:

Każdy obiekt liścia rejestracji reprezentuje dane skojarzone z jedną wersją pakietu.

Wpis wykazu

Właściwość catalogEntry w obiekcie liścia rejestracji ma następujące właściwości:

Właściwość pakietu version jest pełnym ciągiem wersji po normalizacji. Oznacza to, że dane kompilacji SemVer 2.0.0 można uwzględnić tutaj.

Właściwość dependencyGroups jest tablicą obiektów reprezentujących zależności pakietu pogrupowane według platformy docelowej. Jeśli pakiet nie ma zależności, dependencyGroups brakuje właściwości, pustej tablicy lub dependencies właściwości wszystkich grup jest pusta lub brakuje jej.

Wartość licenseExpression właściwości jest zgodna ze składnią wyrażenia licencji NuGet.

Grupa zależności pakietu

Każdy obiekt grupy zależności ma następujące właściwości:

Ciąg targetFramework używa formatu zaimplementowanego przez bibliotekę NuGet.Frameworks biblioteki nuGet.NET. Jeśli nie targetFramework zostanie określony, grupa zależności ma zastosowanie do wszystkich platform docelowych.

Właściwość dependencies jest tablicą obiektów, z których każda reprezentuje zależność pakietu bieżącego pakietu.

Zależność pakietu

Każda zależność pakietu ma następujące właściwości:

range Jeśli właściwość jest wykluczona lub pusty ciąg, klient powinien domyślnie używać zakresu (, )wersji . Oznacza to, że dowolna wersja zależności jest dozwolona. Wartość parametru * jest niedozwolona range dla właściwości .

Przestarzały pakiet

Każda wycofanie pakietu ma następujące właściwości:

Właściwość reasons musi zawierać co najmniej jeden ciąg i powinna zawierać tylko ciągi z poniższej tabeli:

reasons Jeśli właściwość zawiera ciągi, które nie pochodzą ze znanego zestawu, powinny być ignorowane. Ciągi są bez uwzględniania wielkości liter, więc legacy powinny być traktowane tak samo jak Legacy. W tablicy nie ma ograniczeń kolejności, więc ciągi mogą być rozmieszczone w dowolnej kolejności. Ponadto jeśli właściwość zawiera tylko ciągi, które nie pochodzą ze znanego zestawu, powinno być traktowane tak, jakby zawierała tylko ciąg "Inne".

Pakiet alternatywny

Obiekt pakietu alternatywnego ma następujące właściwości:

Luki w zabezpieczeniach

Tablica vulnerability obiektów. Każda luka w zabezpieczeniach ma następujące właściwości:

Przykładowe żądanie

GET https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json

Pamiętaj, aby pobrać podstawowy adres URL (https://api.nuget.org/v3/registration-sample/ w tym przykładzie) z indeksu usługi, jak wspomniano w sekcji podstawowego adresu URL .

Przykładowa odpowiedź

{
  "count": 1,
  "items": [
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json#page/3.0.0-beta/3.0.0-beta",
      "count": 1,
      "items": [
        {
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/3.0.0-beta.json",
          "catalogEntry": {
            "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json",
            "authors": ".NET Foundation",
            "dependencyGroups": [
              {
                "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup",
                "dependencies": [
                  {
                    "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup/nuget.core",
                    "id": "NuGet.Core",
                    "range": "[2.14.0, )",
                    "registration": "https://api.nuget.org/v3/registration-sample/nuget.core/index.json"
                  }
                ]
              }
            ],
            "description": "Core library for creating a Web Application used to host a simple NuGet feed",
            "iconUrl": "",
            "id": "NuGet.Server.Core",
            "language": "",
            "licenseUrl": "https://raw.githubusercontent.com/NuGet/NuGet.Server/dev/LICENSE.txt",
            "listed": true,
            "minClientVersion": "2.6",
            "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg",
            "projectUrl": "https://github.com/NuGet/NuGet.Server",
            "published": "2017-10-05T18:40:32.43+00:00",
            "requireLicenseAcceptance": false,
            "summary": "",
            "tags": [ "" ],
            "title": "",
            "version": "3.0.0-beta",
            "vulnerabilities": [
              {
                "advisoryUrl": "https://github.com/advisories/ABCD-1234-5678-9012",
                "severity": "2"
              }
            ]
          },
          "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg",
          "registration": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json"
        }
      ],
      "lower": "3.0.0-beta",
      "upper": "3.0.0-beta"
    }
  ]
}

W tym konkretnym przypadku indeks rejestracji zawiera stronę rejestracji, dlatego żadne dodatkowe żądania nie są potrzebne do pobierania metadanych dotyczących poszczególnych wersji pakietu.

Strona rejestracji

Strona rejestracji zawiera liście rejestracji. Adres URL pobierania strony rejestracji jest określany przez @id właściwość obiektu strony rejestracji wymienionego powyżej. Adres URL nie jest przewidywalny i powinien być zawsze wykrywany za pomocą dokumentu indeksu.

Jeśli tablica items nie jest podana w indeksie rejestracji, żądanie @id HTTP GET wartości zwróci dokument JSON, który ma obiekt jako główny. Obiekt ma następujące właściwości:

Kształt obiektów liścia rejestracji jest taki sam jak w powyższym indeksie rejestracji.

Przykładowe żądanie

GET https://api.nuget.org/v3/registration-sample/ravendb.client/page/1.0.531/1.0.729-unstable.json

Pamiętaj, aby pobrać podstawowy adres URL (https://api.nuget.org/v3/registration-sample/ w tym przykładzie) z indeksu usługi, jak wspomniano w sekcji podstawowego adresu URL .

Przykładowa odpowiedź

{
  "count": 2,
  "lower": "1.0.531",
  "parent": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json",
  "upper": "1.0.729-unstable",
  "items": [
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.531.json",
      "@type": "Package",
      "commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1",
      "commitTimeStamp": "2017-10-26T14:12:19.3439088Z",
      "catalogEntry": {
        "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.38.37/nuget.protocol.v3.example.1.0.531.json",
        "@type": "PackageDetails",
        "authors": "NuGet.org Team",
        "iconUrl": "https://www.nuget.org/Content/gallery/img/default-package-icon.svg",
        "id": "NuGet.Protocol.V3.Example",
        "licenseUrl": "http://www.opensource.org/licenses/ms-pl",
        "listed": false,
        "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg",
        "projectUrl": "https://github.com/NuGet/NuGetGallery",
        "published": "1900-01-01T00:00:00+00:00",
        "requireLicenseAcceptance": true,
        "title": "NuGet V3 Protocol Example",
        "version": "1.0.531"
      },
      "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg",
      "registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json"
    },
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.729-unstable.json",
      "@type": "Package",
      "commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1",
      "commitTimeStamp": "2017-10-26T14:12:19.3439088Z",
      "catalogEntry": {
        "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.18.22.05/nuget.protocol.v3.example.1.0.729-unstable.json",
        "@type": "PackageDetails",
        "authors": "NuGet.org Team",
        "deprecation": {
          "reasons": [
            "CriticalBugs"
          ],
          "message": "This package is unstable and broken!",
          "alternatePackage": {
            "id": "Newtonsoft.JSON",
            "range": "12.0.2"
          }
        },
        "iconUrl": "https://www.nuget.org/Content/gallery/img/default-package-icon.svg",
        "id": "NuGet.Protocol.V3.Example",
        "licenseUrl": "http://www.opensource.org/licenses/ms-pl",
        "listed": false,
        "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg",
        "projectUrl": "https://github.com/NuGet/NuGetGallery",
        "published": "1900-01-01T00:00:00+00:00",
        "requireLicenseAcceptance": true,
        "summary": "This package is an example for the V3 protocol.",
        "title": "NuGet V3 Protocol Example",
        "version": "1.0.729-Unstable"
      },
      "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg",
      "registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json"
    }
  ]
}

Liść rejestracji

Liść rejestracji zawiera informacje o określonym identyfikatorze pakietu i wersji. Metadane dotyczące określonej wersji mogą nie być dostępne w tym dokumencie. Metadane pakietu należy pobrać z indeksu rejestracji lub strony rejestracji (która została odnaleziona przy użyciu indeksu rejestracji).

Adres URL pobierania liścia rejestracji jest uzyskiwany z @id właściwości obiektu liścia rejestracji na stronie indeksu rejestracji lub rejestracji. Podobnie jak w przypadku dokumentu strony. adres URL nie jest przewidywalny i powinien być zawsze wykrywany za pomocą obiektu strony rejestracji.

Liść rejestracji jest dokumentem JSON z obiektem głównym o następujących właściwościach:

Przykładowe żądanie

GET https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json

Pamiętaj, aby pobrać podstawowy adres URL (https://api.nuget.org/v3/registration-sample/ w tym przykładzie) z indeksu usługi, jak wspomniano w sekcji podstawowego adresu URL .

Przykładowa odpowiedź

{
  "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json",
  "catalogEntry": "https://api.nuget.org/v3/catalog0/data/2017.08.11.18.24.22/nuget.versioning.4.3.0.json",
  "listed": true,
  "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.versioning/4.3.0/nuget.versioning.4.3.0.nupkg",
  "published": "2017-08-11T18:24:14.36+00:00",
  "registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.json"
}