Метаданные пакета

Статья
10/23/2023

Вы можете получить метаданные о пакетах, доступных в источнике пакетов, с помощью API NuGet версии 3. Эти метаданные можно получить с помощью ресурса, найденного RegistrationsBaseUrl в индексе службы.

Коллекция документов, найденных в разделе RegistrationsBaseUrl , часто называются "регистрациями" или "большими двоичными объектами регистрации". Набор документов под одним RegistrationsBaseUrl называется "hive регистрации". Куст регистрации содержит метаданные о каждом пакете, доступном в источнике пакета.

Примечание.

Ресурс метаданных пакета не содержит все метаданные для пакетов. Используйте ресурс поиска для поиска владельцев пакетов, загрузки или состояния резервирования префикса.

Управление версиями

Допустимы следующие значения @type:

Значение @type	Примечания.
RegistrationsBaseUrl	Начальный выпуск
RegistrationsBaseUrl/3.0.0-beta	Псевдоним `RegistrationsBaseUrl`
RegistrationsBaseUrl/3.0.0-rc	Псевдоним `RegistrationsBaseUrl`
RegistrationsBaseUrl/3.4.0	Gzipped responses
RegistrationsBaseUrl/3.6.0	Включает пакеты SemVer 2.0.0

Это представляет три отдельных куста регистрации, доступных для различных версий клиента.

RegistrationsBaseUrl

Эти регистрации не сжимаются (это означает, что они используют подразумеваемый Content-Encoding: identity). Пакеты SemVer 2.0.0 исключены из этого куста.

RegistrationsBaseUrl/3.4.0

Эти регистрации сжимаются с помощью Content-Encoding: gzip. Пакеты SemVer 2.0.0 исключены из этого куста.

RegistrationsBaseUrl/3.6.0

Эти регистрации сжимаются с помощью Content-Encoding: gzip. Пакеты SemVer 2.0.0 включены в этот hive. Дополнительные сведения о поддержке SemVer 2.0.0 см. в статье о поддержке SemVer 2.0.0 для nuget.org.

Базовый URL-адрес

Базовый URL-адрес для следующих API — это значение свойства, связанного @id с указанными выше значениями ресурсов @type упоминание. В следующем документе будет использоваться базовый URL-адрес заполнителя {@id}. Базовый URL-адрес может изменяться на основе изменений в реализации или инфраструктуре в источнике пакета, поэтому он должен быть динамически получен из индекса службы клиентским программным обеспечением.

Методы HTTP

Все URL-адреса, содержащиеся в ресурсе регистрации, поддерживают методы HTTP GET и HEAD.

Индекс регистрации

Метаданные пакета групп ресурсов регистрации по идентификатору пакета. Невозможно получить данные о нескольких идентификаторах пакета одновременно. Этот ресурс не позволяет обнаруживать идентификаторы пакетов. Вместо этого предполагается, что клиент уже знает нужный идентификатор пакета. Доступные метаданные о каждой версии пакета зависят от реализации сервера. Большие двоичные объекты регистрации пакетов имеют следующую иерархическую структуру:

Индекс: точка входа для метаданных пакета, общая для всех пакетов в источнике с одинаковым идентификатором пакета.
Страница: группирование версий пакетов. Количество версий пакетов на странице определяется реализацией сервера.
Лист: документ, относяющийся к одной версии пакета.

URL-адрес индекса регистрации предсказуем и может быть определен клиентом с идентификатором пакета и значением ресурса @id регистрации из индекса службы. URL-адреса страниц регистрации и листьев обнаруживаются путем проверки индекса регистрации.

Страницы регистрации и листья

Хотя для реализации сервера не требуется хранить конечные листы регистрации в отдельных документах страницы регистрации, рекомендуется сохранять память на стороне клиента. Вместо того чтобы встраивать все листья регистрации в индексе или немедленно хранить листья в документах страниц, рекомендуется, чтобы реализация сервера определила некоторые эвристические способы выбора между двумя подходами на основе количества версий пакета или накопительного размера листьев пакета.

Хранение всех версий пакетов (оставляет) в индексе регистрации экономит количество HTTP-запросов, необходимых для получения метаданных пакета, но означает, что необходимо скачать больший документ и выделить больше памяти клиента. С другой стороны, если реализация сервера немедленно сохраняет выходы регистрации в отдельных документах страниц, клиент должен выполнить дополнительные HTTP-запросы, чтобы получить необходимую информацию.

Эвристика, которая используется nuget.org, выглядит следующим образом: если существует 128 или более версий пакета, разорвать листья на страницы размером 64. Если существует менее 128 версий, все встраиваются в индекс регистрации. Обратите внимание, что это означает, что пакеты с 65-127 версиями будут иметь две страницы в индексе, но обе страницы будут встраиваться.

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

Параметры запроса

Имя.	In	Тип	Обязательное поле	Примечания.
LOWER_ID	URL	строка	yes	Идентификатор пакета, нижний регистр

Значение LOWER_ID — это требуемый идентификатор пакета, нижний регистр с помощью правил, реализованных в . System.String.ToLowerInvariant() Метод NET.

Response

Ответ — это документ JSON, имеющий корневой объект со следующими свойствами:

Имя.	Type	Обязательное поле	Примечания.
count	integer	yes	Количество страниц регистрации в индексе
items	массив объектов	yes	Массив страниц регистрации

Каждый элемент в массиве объекта items индекса представляет собой объект JSON, представляющий страницу регистрации.

Объект страницы регистрации

Объект страницы регистрации, найденный в индексе регистрации, имеет следующие свойства:

Имя.	Type	Обязательное поле	Примечания.
@id	строка	yes	URL-адрес страницы регистрации
count	integer	yes	Количество выходов регистрации на странице
items	массив объектов	no	Массив отпусков регистрации и их сопоставленных метаданных
lower	строка	yes	Самая низкая версия SemVer 2.0.0 на странице (включительно)
parent	строка	no	URL-адрес индекса регистрации
upper	строка	yes	Самая высокая версия SemVer 2.0.0 на странице (включительно)

upper Границы lower объекта страницы полезны при необходимости метаданных для определенной версии страницы. Эти границы можно использовать для получения только необходимой страницы регистрации. Строки версии соответствуют правилам версии NuGet. Строки версии нормализуются и не включают метаданные сборки. Как и во всех версиях экосистемы NuGet, сравнение строк версий реализуется с помощью правил приоритета версий SemVer 2.0.0.

Свойство parent будет отображаться только в том случае, если объект страницы регистрации имеет items свойство.

items Если свойство отсутствует в объекте страницы регистрации, URL-адрес, указанный в @id файле, должен использоваться для получения метаданных о отдельных версиях пакетов. Массив items иногда исключается из объекта страницы в качестве оптимизации. Если количество версий одного идентификатора пакета очень велико, документ индекса регистрации будет массовым и расточительным для обработки для клиента, который заботится только о конкретной версии или небольшом диапазоне версий.

Обратите внимание, что если items свойство присутствует, свойство не нужно использовать, @id так как все данные страницы уже встраиваются в items свойство.

Каждый элемент в массиве объекта items страницы представляет собой объект JSON, представляющий лист регистрации, и он связан с метаданными.

Конечный объект регистрации на странице

Конечный объект регистрации, найденный на странице регистрации, имеет следующие свойства:

Имя.	Type	Обязательное поле	Примечания.
@id	строка	yes	URL-адрес конечной точки регистрации
catalogEntry	объект	yes	Запись каталога, содержащая метаданные пакета
packageContent	строка	yes	URL-адрес содержимого пакета (NUPKG)

Каждый конечный объект регистрации представляет данные, связанные с одной версией пакета.

Запись каталога

Свойство в конечном объекте catalogEntry регистрации имеет следующие свойства:

Имя.	Type	Обязательное поле	Примечания.
@id	строка	yes	URL-адрес документа, используемого для создания этого объекта
authors	строка или массив строк	no
зависимостиGroups	массив объектов	no	Зависимости пакета, сгруппированные по целевой платформе
Исключения	объект	no	Нерекомендуемая связь с пакетом
описание	строка	no
iconUrl	строка	no
id	string	yes	Идентификатор пакета
язык	string	no
licenseUrl	строка	no
licenseExpression	строка	no
регионе.	boolean	no	Следует рассматривать как указанный в списке, если отсутствует
minClientVersion	строка	no
packageContent	строка	no	Дублирование того же свойства в родительском объекте, включенное только по устаревшим причинам
projectUrl	строка	no
published	строка	no	Строка, содержащая метку времени ISO 8601 при публикации пакета
readmeUrl	строка	no	URL-адрес представления отрисованной (HTML-веб-страницы) пакета README
requireLicenseAcceptance	boolean	no
Итоги	строка	no
tags	строка или массив строк	no
title	string	no
версия	строка	yes	Полная строка версии после нормализации
vulnerabilities	массив объектов	no	Уязвимости пакета безопасности

Свойство пакета version — это полная строка версии после нормализации. Это означает, что данные сборки SemVer 2.0.0 можно включить здесь.

Свойство dependencyGroups представляет собой массив объектов, представляющих зависимости пакета, сгруппированные по целевой платформе. Если пакет не имеет зависимостей, свойство отсутствует, dependencyGroups пустой массив или dependencies свойство всех групп пусто или отсутствует.

Значение свойства соответствует синтаксису licenseExpressionвыражения лицензии NuGet.

Примечание.

В nuget.org published значение задается годом 1900, когда пакет не указан.

Группа зависимостей пакета

Каждый объект группы зависимостей имеет следующие свойства:

Имя.	Type	Обязательное поле	Примечания.
targetFramework	строка	no	Целевая платформа, к которым применимы эти зависимости.
dependencies	массив объектов	no

Строка targetFramework использует формат, реализованный библиотекой NuGet .NET NuGet.Frameworks. Если не targetFramework указано, группа зависимостей применяется ко всем целевым платформам.

Свойство dependencies представляет собой массив объектов, каждый из которых представляет зависимость пакета текущего пакета.

Зависимость пакета

Каждая зависимость пакета имеет следующие свойства:

Имя.	Type	Обязательное поле	Примечания.
id	string	yes	Идентификатор зависимости пакета
range	объект	no	Допустимый диапазон версий зависимости
регистрация	строка	no	URL-адрес индекса регистрации для этой зависимости

range Если свойство исключается или пустая строка, клиент должен по умолчанию использовать диапазон (, )версий. То есть разрешена любая версия зависимости. Значение * не допускается для range свойства.

Объявление пакетов нерекомендуемыми

У каждого пакета нерекомендуются следующие свойства:

Имя.	Type	Обязательное поле	Примечания.
Причин	массив строк	yes	Причины, по которым пакет не рекомендуется
message	строка	no	Дополнительные сведения об этом нерекомендуемом
alternatePackage	объект	no	Альтернативный пакет, который следует использовать вместо него

Свойство reasons должно содержать по крайней мере одну строку и содержать только строки из следующей таблицы:

Причина	Description
Устарело	Пакет больше не поддерживается
Критически важныеbugs	Пакет содержит ошибки, которые делают его непригодным для использования
Другие	Пакет устарел из-за причины, не связанной с этим списком

reasons Если свойство содержит строки, которые не относятся к известному набору, их следует игнорировать. Строки не учитывает регистр, поэтому legacy их следует рассматривать так же, как Legacy. В массиве нет ограничений по упорядочению, поэтому строки могут упорядочиться в любом произвольном порядке. Кроме того, если свойство содержит только строки, которые не относятся к известному набору, он должен рассматриваться как если бы он содержал только строку "Other".

Альтернативный пакет

Альтернативный объект пакета имеет следующие свойства:

Имя.	Type	Обязательное поле	Примечания.
id	string	yes	Идентификатор альтернативного пакета
range	объект	no	Допустимый диапазон версий или `*` разрешенная версия

Уязвимости

Массив объектов vulnerability. Каждая уязвимость имеет следующие свойства:

Имя.	Type	Обязательное поле	Примечания.
advisoryUrl	строка	yes	Расположение рекомендаций по безопасности пакета
severity	строка	yes	Серьезность рекомендаций: "0" = низкий, "1" = умеренный, "2" = высокий, "3" = критическое

Образец запроса

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

Обязательно получите базовый URL-адрес (https://api.nuget.org/v3/registration-sample/в этом примере) из индекса службы, как упоминание в разделе базового URL-адреса.

Пример ответа

{
  "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"
    }
  ]
}

В этом случае индекс регистрации содержит вложенную страницу регистрации, поэтому дополнительные запросы не требуются для получения метаданных о отдельных версиях пакетов.

Страница регистрации

Страница регистрации содержит листья регистрации. URL-адрес для получения страницы регистрации определяется @id свойством в объекте страницы регистрации, упоминание выше. URL-адрес не должен быть предсказуемым и всегда должен быть обнаружен с помощью документа индекса.

Предупреждение

В nuget.org URL-адрес документа страницы регистрации совпадает с нижней и верхней границой страницы. Однако это предположение никогда не должно быть сделано клиентом, так как реализации сервера могут изменять форму URL-адреса до тех пор, пока документ индекса имеет допустимую ссылку.

items Если массив не указан в индексе регистрации, http-запрос @id GET значения вернет документ JSON, имеющий объект в качестве корневого элемента. Объект имеет следующие свойства.

Имя.	Type	Обязательное поле	Примечания.
@id	строка	yes	URL-адрес страницы регистрации
count	integer	yes	Количество выходов регистрации на странице
items	массив объектов	yes	Массив отпусков регистрации и их сопоставленных метаданных
lower	строка	yes	Самая низкая версия SemVer 2.0.0 на странице (включительно)
parent	строка	yes	URL-адрес индекса регистрации
upper	строка	yes	Самая высокая версия SemVer 2.0.0 на странице (включительно)

Форма конечных объектов регистрации аналогична приведенному выше индексу регистрации.

Образец запроса

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

Пример ответа

{
  "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"
    }
  ]
}

Лист регистрации

Лист регистрации содержит сведения о конкретном идентификаторе пакета и версии. Метаданные конкретной версии могут быть недоступны в этом документе. Метаданные пакета следует получить из индекса регистрации или страницы регистрации (которая обнаружена с помощью индекса регистрации).

URL-адрес для получения конечной точки регистрации получен из @id свойства конечного объекта регистрации в индексе регистрации или на странице регистрации. Как и в документе страницы. URL-адрес не должен быть предсказуемым и всегда должен быть обнаружен с помощью объекта страницы регистрации.

Предупреждение

В nuget.org URL-адрес для конечного документа регистрации случайно содержит версию пакета. Однако это предположение никогда не должно быть сделано клиентом, так как реализации сервера могут изменять форму URL-адреса, если родительский документ имеет действительную ссылку.

Лист регистрации — это документ JSON с корневым объектом со следующими свойствами:

Имя.	Type	Обязательное поле	Примечания.
@id	строка	yes	URL-адрес конечной точки регистрации
catalogEntry	строка	no	URL-адрес записи каталога, создающей эти конечные страницы
регионе.	boolean	no	Следует рассматривать как указанный в списке, если отсутствует
packageContent	строка	no	URL-адрес содержимого пакета (NUPKG)
published	строка	no	Строка, содержащая метку времени ISO 8601 при публикации пакета
регистрация	строка	no	URL-адрес индекса регистрации

Примечание.

В nuget.org published значение задается годом 1900, когда пакет не указан.

Образец запроса

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

Пример ответа

{
  "@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"
}

Поделиться через

Метаданные пакета

Управление версиями

RegistrationsBaseUrl

RegistrationsBaseUrl/3.4.0

RegistrationsBaseUrl/3.6.0

Базовый URL-адрес

Методы HTTP

Индекс регистрации

Страницы регистрации и листья

Параметры запроса

Response

Объект страницы регистрации

Конечный объект регистрации на странице

Запись каталога

Группа зависимостей пакета

Зависимость пакета

Объявление пакетов нерекомендуемыми

Альтернативный пакет

Уязвимости

Образец запроса

Пример ответа

Страница регистрации

Образец запроса

Пример ответа

Лист регистрации

Образец запроса

Пример ответа

Обратная связь

Дополнительные ресурсы