Индекс службы

Статья
08/10/2023

Индекс службы — это документ JSON, который является точкой входа для источника пакета NuGet и позволяет клиентской реализации обнаруживать возможности источника пакета. Индекс службы — это объект JSON с двумя обязательными свойствами: version (версия схемы индекса службы) и resources (конечные точки или возможности источника пакета).

Индекс службы nuget.org находится здесь: https://api.nuget.org/v3/index.json.

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

Значение version является строкой версии SemVer 2.0.0, которая указывает версию схемы индекса службы. API требует, чтобы строка версии представляла основной номер версии 3. Так как в схему индекса службы вносятся некритические изменения, дополнительный номер версии в строке версии увеличится.

Каждый ресурс в индексе службы обновляется независимо от версии схемы индекса службы.

Текущая версия схемы — 3.0.0. Эта версия 3.0.0 функционально эквивалентна более старой версии 3.0.0-beta.1, но ее следует предпочесть, так как она более четко представляет стабильную определенную схему.

Методы HTTP

Индекс службы можно получить с помощью методов HTTP GET и HEAD.

Ресурсы

Свойство resources содержит массив ресурсов, поддерживаемых этим источником пакета.

Ресурс

Ресурс — это объект в массиве resources. Он представляет возможность источника пакета с определенной версией. Ресурс имеет следующие свойства:

Имя.	Type	Обязательное поле	Примечания.
@id	строка	yes	URL-адрес ресурса.
@type	строка	yes	Строковая константа, представляющая тип объекта.
Комментарий	строка	no	Понятное описание ресурса.

@id — это URL-адрес, который должен быть абсолютным и должен иметь схему HTTP или HTTPS.

@type используется для определения конкретного протокола, используемого при взаимодействии с ресурсом. Тип ресурса является непрозрачной строкой, но обычно имеет следующий формат:

{RESOURCE_NAME}/{RESOURCE_VERSION}

Клиенты должны прописывать в коде значения @type, которые они понимают, чтобы находить их в индексе службы источника пакета. Точные значения @type, используемые сегодня, перечислены в справочных документах по отдельным ресурсам, перечисленных в разделе Обзор API.

Соответствующая документация по различным ресурсам будет по существу сгруппирована по {RESOURCE_NAME} в индексе службы, что аналогично группировке по сценарию.

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

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

GET https://api.nuget.org/v3/index.json

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

{
  "version": "3.0.0",
  "resources": [
    {
      "@id": "https://api.nuget.org/v3-flatcontainer/",
      "@type": "PackageBaseAddress/3.0.0",
      "comment": "Base URL of Azure storage where NuGet package registration info for NET Core is stored, in the format https://api.nuget.org/v3-flatcontainer/{id-lower}/{id-lower}.{version-lower}.nupkg"
    },
    {
      "@id": "https://www.nuget.org/api/v2/package",
      "@type": "PackagePublish/2.0.0"
    },
    {
      "@id": "https://api-v2v3search-0.nuget.org/query",
      "@type": "SearchQueryService/3.0.0-rc",
      "comment": "Query endpoint of NuGet Search service (primary) used by RC clients"
    },
    {
      "@id": "https://api-v2v3search-0.nuget.org/autocomplete",
      "@type": "SearchAutocompleteService/3.0.0-rc",
      "comment": "Autocomplete endpoint of NuGet Search service (primary) used by RC clients"
    },
    {
      "@id": "https://api.nuget.org/v3/registration2/",
      "@type": "RegistrationsBaseUrl/3.0.0-rc",
      "comment": "Base URL of Azure storage where NuGet package registration info is stored used by RC clients. This base URL does not include SemVer 2.0.0 packages."
    }
  ]
}