Índice de servicio

Artigo
12/19/2023

El índice de servicio es un documento JSON que es el punto de entrada de un origen de paquete NuGet y permite que una implementación de cliente detecte las funcionalidades del origen del paquete. El índice de servicio es un objeto JSON con dos propiedades necesarias: version (la versión de esquema del índice de servicio) y resources (los puntos de conexión o las funcionalidades del origen del paquete).

El índice de servicio de nuget.org se encuentra en https://api.nuget.org/v3/index.json.

Control de versiones

El valor version es una cadena de versión analizable de SemVer 2.0.0 que indica la versión del esquema del índice de servicio. La API exige que la cadena de versión tenga un número de versión principal de 3. A medida que se realicen cambios no importantes en el esquema del índice de servicio, se incrementará la versión secundaria de la cadena de versión.

Cada recurso del índice de servicio tiene versiones independientes de la versión del esquema del índice de servicio.

La versión del esquema actual es 3.0.0. La versión 3.0.0 es funcionalmente equivalente a la antigua versión 3.0.0-beta.1, pero debería preferirse porque comunica más claramente el esquema estable y definido.

Métodos HTTP

El índice de servicio es accesible mediante los métodos HTTP GET y HEAD.

Recursos

La propiedad resources contiene una matriz de recursos admitidos por este origen de paquete.

Resource

Un recurso es un objeto en la matriz resources. Representa una funcionalidad con control de versiones de un origen de paquete. Un recurso tiene las siguientes propiedades:

Nombre	Type	Obligatorio	Notas
@id	string	sí	Dirección URL del recurso
@type	string	sí	Constante de cadena que representa el tipo de recurso
comentario	string	no	Descripción legible del recurso

@id es una dirección URL que debe ser absoluta y debe tener el esquema HTTP o HTTPS.

@type se usa para identificar el protocolo específico que se va a usar al interactuar con el recurso. El tipo del recurso es una cadena opaca, pero generalmente tiene el formato:

{RESOURCE_NAME}/{RESOURCE_VERSION}

Se espera que los clientes codifiquen de forma rígida los valores @type que entienden y los busquen en el índice de servicios del origen de un paquete. Los valores @type exactos que se usan actualmente se enumeran en los documentos de referencia de recursos individuales que figuran en la información general de la API.

Para esta documentación, la documentación sobre los diferentes recursos se agrupará esencialmente por el valor {RESOURCE_NAME} que se encuentra en el índice del servicio, que es análogo a la agrupación por escenario.

No hay ningún requisito de que cada recurso tenga un único @id o @type. Es la implementación del cliente la que determina qué recurso preferir sobre otro. Una posible implementación es que los recursos del mismo @type, o compatible, puedan utilizarse según un modelo round-robin en caso de error de conexión o del servidor.

Solicitud de ejemplo

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

Respuesta de muestra

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

Compartir por