Índice de serviço

Artigo
12/22/2023

O índice de serviço é um documento JSON que é o ponto de entrada para uma origem de pacote do NuGet e permite que uma implementação de cliente descubra os recursos da origem do pacote. O índice de serviço é um objeto JSON com duas propriedades necessárias: version (a versão do esquema do índice de serviço) e resources (os pontos de extremidade ou recursos da origem do pacote).

O índice de serviços do nuget.org está localizado em https://api.nuget.org/v3/index.json.

Controle de versão

O valor de version é uma cadeia de caracteres de versão analisável do SemVer 2.0.0 que indica a versão do esquema do índice de serviço. A API exige que a cadeia de caracteres da versão tenha um número de versão principal de 3. À medida que alterações sem interrupção são feitas no esquema de índice de serviço, a versão secundária da cadeia de caracteres da versão será aumentada.

Cada recurso no índice de serviço é versionado independentemente da versão do esquema de índice de serviço.

A versão atual do esquema é 3.0.0. A versão 3.0.0 é funcionalmente equivalente à versão 3.0.0-beta.1 mais antiga, mas deve ser preferida, pois comunica mais claramente o esquema estável e definido.

Métodos HTTP

O índice de serviço é acessível usando métodos HTTP GET e HEAD.

Recursos

A propriedade resources contém uma matriz de recursos suportados por esta origem de pacote.

Recurso

Um recurso é um objeto na matriz resources. Ele representa um recurso versionado de uma origem de pacote. Um recurso tem as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
@id	string	sim	A URL para o recurso
@type	string	sim	Uma constante de cadeia de caracteres que representa o tipo de recurso
comment	string	não	Uma descrição legível por humanos do recurso

O @id é uma URL que deve ser absoluta e deve ter o esquema HTTP ou HTTPS.

O @type é usado para identificar o protocolo específico a ser usado ao interagir com o recurso. O tipo do recurso é uma cadeia de caracteres opaca, mas geralmente tem o formato:

{RESOURCE_NAME}/{RESOURCE_VERSION}

Espera-se que os clientes codifiquem os valores de @type que entendem e os procurem no índice de serviço de uma fonte de pacote. Os valores exatos de @type em uso hoje são enumerados nos documentos de referência de recursos individuais listados na visão geral da API.

Para fins desta documentação, a documentação sobre diferentes recursos será essencialmente agrupada pelo {RESOURCE_NAME} encontrado no índice de serviço, que é análogo ao agrupamento por cenário.

Não há exigência de que cada recurso tenha um único @id ou @type. Cabe à implementação do cliente determinar qual recurso prefere em detrimento de outro. Uma implementação possível é que recursos do mesmo @type ou compatíveis com ele podem ser usados com distribuição equilibrada em caso de falha de conexão ou erro do servidor.

Solicitação de exemplo

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

Resposta de exemplo

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

Compartilhar via