Condividi tramite

Metadati dei pacchetti

  • Articolo

È possibile recuperare i metadati relativi ai pacchetti disponibili in un'origine del pacchetto usando l'API NuGet V3. Questi metadati possono essere recuperati usando la RegistrationsBaseUrl risorsa trovata nell'indice del servizio.

La raccolta dei documenti presenti in RegistrationsBaseUrl è spesso denominata "registrazioni" o "BLOB di registrazione". Il set di documenti in un singolo RegistrationsBaseUrl oggetto viene definito "hive di registrazione". Un hive di registrazione contiene metadati relativi a ogni pacchetto disponibile in un'origine del pacchetto.

Nota

La risorsa dei metadati del pacchetto non contiene tutti i metadati per i pacchetti. Usare la risorsa di ricerca per trovare i proprietari, i download o lo stato della prenotazione con prefisso dei pacchetti.

Controllo delle versioni

Vengono usati i valori seguenti @type :

Valore @type Note
RegistrationsBaseUrl Versione iniziale
RegistrationsBaseUrl/3.0.0-beta Alias di RegistrationsBaseUrl
RegistrationsBaseUrl/3.0.0-rc Alias di RegistrationsBaseUrl
RegistrationsBaseUrl/3.4.0 Risposte con gzipped
RegistrationsBaseUrl/3.6.0 Include pacchetti SemVer 2.0.0

Rappresenta tre hive di registrazione distinte disponibili per varie versioni client.

RegistrationsBaseUrl

Queste registrazioni non vengono compresse ( ovvero usano un implicito Content-Encoding: identity). I pacchetti SemVer 2.0.0 vengono esclusi da questo hive.

RegistrationsBaseUrl/3.4.0

Queste registrazioni vengono compresse tramite Content-Encoding: gzip. I pacchetti SemVer 2.0.0 vengono esclusi da questo hive.

RegistrationsBaseUrl/3.6.0

Queste registrazioni vengono compresse tramite Content-Encoding: gzip. I pacchetti SemVer 2.0.0 sono inclusi in questo hive. Per altre informazioni su SemVer 2.0.0, vedere Supporto semVer 2.0.0 per nuget.org.

URL di base

L'URL di base per le API seguenti è il valore della @id proprietà associata ai valori delle risorse menzionati in precedenza @type . Nel documento seguente verrà usato l'URL {@id} di base segnaposto. L'URL di base può cambiare in base alle modifiche dell'implementazione o dell'infrastruttura all'interno dell'origine del pacchetto, pertanto deve essere recuperato dinamicamente dall'indice del servizio dal software client.

Metodi HTTP

Tutti gli URL trovati nella risorsa di registrazione supportano i metodi GET HTTP e HEAD.

Indice di registrazione

I metadati del pacchetto dei gruppi di risorse di registrazione in base all'ID pacchetto. Non è possibile ottenere dati su più ID pacchetto alla volta. Questa risorsa non consente di individuare gli ID pacchetto. Si presuppone invece che il client conosca già l'ID del pacchetto desiderato. I metadati disponibili per ogni versione del pacchetto variano in base all'implementazione del server. I BLOB di registrazione del pacchetto hanno la struttura gerarchica seguente:

  • Indice: punto di ingresso per i metadati del pacchetto, condiviso da tutti i pacchetti in un'origine con lo stesso ID pacchetto.
  • Pagina: raggruppamento di versioni del pacchetto. Il numero di versioni del pacchetto in una pagina è definito dall'implementazione del server.
  • Foglia: documento specifico di una singola versione del pacchetto.

L'URL dell'indice di registrazione è prevedibile e può essere determinato dal client in base a un ID pacchetto e al valore della risorsa di registrazione dall'indice del @id servizio. Gli URL per le pagine di registrazione e le foglie vengono individuati controllando l'indice di registrazione.

Pagine di registrazione e foglie

Sebbene non sia strettamente necessario per un'implementazione del server archiviare le foglia di registrazione in documenti di pagina di registrazione separati, è consigliabile risparmiare memoria sul lato client. Invece di inlining di tutte le foglie di registrazione nell'indice o di archiviare immediatamente le foglie nei documenti di pagina, è consigliabile che l'implementazione del server definisci un'euristica tra i due approcci in base al numero di versioni del pacchetto o alla dimensione cumulativa delle foglie del pacchetto.

L'archiviazione di tutte le versioni del pacchetto (foglie) nell'indice di registrazione consente di risparmiare sul numero di richieste HTTP necessarie per recuperare i metadati del pacchetto, ma significa che è necessario scaricare un documento di dimensioni maggiori e allocare una quantità maggiore di memoria client. D'altra parte, se l'implementazione del server archivia immediatamente le foglie di registrazione in documenti di pagina separati, il client deve eseguire più richieste HTTP per ottenere le informazioni necessarie.

L'euristica utilizzata nuget.org è la seguente: se sono presenti 128 o più versioni di un pacchetto, suddividere le foglie in pagine di dimensioni 64. Se sono presenti meno di 128 versioni, inline tutte le foglie nell'indice di registrazione. Si noti che questo significa che i pacchetti con versioni da 65 a 127 avranno due pagine nell'indice, ma entrambe le pagine verranno inlinedi.

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

Parametri della richiesta

Nome Tra Type Obbligatorio Note
LOWER_ID URL string yes ID pacchetto, in minuscolo

Il LOWER_ID valore è l'ID pacchetto desiderato in minuscolo usando le regole implementate da . Metodo di System.String.ToLowerInvariant() NET.

Response

La risposta è un documento JSON con un oggetto radice con le proprietà seguenti:

Nome Digita Obbligatorio Note
numero integer yes Numero di pagine di registrazione nell'indice
articoli matrice di oggetti yes Matrice di pagine di registrazione

Ogni elemento nella matrice dell'oggetto items index è un oggetto JSON che rappresenta una pagina di registrazione.

Oggetto pagina di registrazione

L'oggetto pagina di registrazione presente nell'indice di registrazione ha le proprietà seguenti:

Nome Digita Obbligatorio Note
@id string yes URL della pagina di registrazione
numero integer yes Numero di foglie di registrazione nella pagina
articoli matrice di oggetti no Matrice di foglie di registrazione e dei relativi metadati associati
lower string yes La versione più bassa di SemVer 2.0.0 nella pagina (inclusa)
parent string no URL dell'indice di registrazione
upper string yes Versione più alta di SemVer 2.0.0 nella pagina (inclusa)

I lower limiti e upper dell'oggetto pagina sono utili quando sono necessari i metadati per una versione di pagina specifica. Questi limiti possono essere usati per recuperare l'unica pagina di registrazione necessaria. Le stringhe di versione rispettano le regole di versione di NuGet. Le stringhe di versione vengono normalizzate e non includono i metadati di compilazione. Come per tutte le versioni nell'ecosistema NuGet, il confronto delle stringhe di versione viene implementato usando le regole di precedenza della versione di SemVer 2.0.0.

La parent proprietà verrà visualizzata solo se l'oggetto pagina di registrazione ha la items proprietà .

Se la items proprietà non è presente nell'oggetto pagina di registrazione, è necessario utilizzare l'URL specificato in @id per recuperare i metadati relativi alle singole versioni del pacchetto. La items matrice viene talvolta esclusa dall'oggetto pagina come ottimizzazione. Se il numero di versioni di un singolo ID pacchetto è molto grande, il documento di indice di registrazione sarà enorme e sprecato per elaborare per un client che si occupa solo di una versione specifica o di un intervallo ridotto di versioni.

Si noti che se la items proprietà è presente, la @id proprietà non deve essere utilizzata, poiché tutti i dati della pagina sono già inlined nella items proprietà .

Ogni elemento nella matrice dell'oggetto pagina items è un oggetto JSON che rappresenta una foglia di registrazione ed è associato ai metadati.

Oggetto foglia di registrazione in una pagina

L'oggetto foglia di registrazione trovato in una pagina di registrazione ha le proprietà seguenti:

Nome Digita Obbligatorio Note
@id string yes URL della foglia di registrazione
catalogEntry oggetto yes Voce del catalogo contenente i metadati del pacchetto
packageContent string yes URL del contenuto del pacchetto (.nupkg)

Ogni oggetto foglia di registrazione rappresenta i dati associati a una singola versione del pacchetto.

Voce del catalogo

La catalogEntry proprietà nell'oggetto foglia di registrazione ha le proprietà seguenti:

Nome Digita Obbligatorio Note
@id string yes URL del documento utilizzato per produrre questo oggetto
authors Stringa o matrice di stringhe no
dependencyGroups matrice di oggetti no Dipendenze del pacchetto, raggruppate per framework di destinazione
Disapprovazione object no Deprecazione associata al pacchetto
description stringa no
iconUrl string no
id string yes ID del pacchetto
lingua string no
licenseUrl string no
licenseExpression string no
disponibili boolean no Deve essere considerato come elencato se assente
minClientVersion string no
packageContent string no Duplicato della stessa proprietà nell'oggetto padre, incluso solo per motivi legacy
projectUrl string no
published string no Stringa contenente un timestamp ISO 8601 di quando il pacchetto è stato pubblicato
readmeUrl string no URL per la visualizzazione (pagina Web HTML) del pacchetto README
requireLicenseAcceptance boolean no
riepilogo string no
tag Stringa o matrice di stringhe no
title string no
versione string yes Stringa di versione completa dopo la normalizzazione
vulnerabilità matrice di oggetti no Vulnerabilità di sicurezza del pacchetto

La proprietà del pacchetto version è la stringa di versione completa dopo la normalizzazione. Ciò significa che i dati di compilazione semVer 2.0.0 possono essere inclusi qui.

La dependencyGroups proprietà è una matrice di oggetti che rappresentano le dipendenze del pacchetto, raggruppate per framework di destinazione. Se il pacchetto non ha dipendenze, la dependencyGroups proprietà è mancante, una matrice vuota o la dependencies proprietà di tutti i gruppi è vuota o mancante.

Il valore della licenseExpression proprietà è conforme alla sintassi dell'espressione di licenza NuGet.

Nota

In nuget.org, il valore viene impostato sull'anno published 1900 quando il pacchetto non è elencato.

Gruppo di dipendenze del pacchetto

Ogni oggetto gruppo di dipendenze ha le proprietà seguenti:

Nome Digita Obbligatorio Note
targetFramework string no Framework di destinazione a cui queste dipendenze sono applicabili
dipendenze matrice di oggetti no

La targetFramework stringa usa il formato implementato dalla libreria .NET di NuGet.Frameworks. Se non viene specificato alcun valore targetFramework , il gruppo di dipendenze si applica a tutti i framework di destinazione.

La dependencies proprietà è una matrice di oggetti, ognuno che rappresenta una dipendenza del pacchetto del pacchetto corrente.

Dipendenza del pacchetto

Ogni dipendenza del pacchetto ha le proprietà seguenti:

Nome Digita Obbligatorio Note
id string yes ID della dipendenza del pacchetto
range object no Intervallo di versioni consentito della dipendenza
registrazione string no URL dell'indice di registrazione per questa dipendenza

Se la range proprietà è esclusa o una stringa vuota, per impostazione predefinita il client deve essere impostato sull'intervallo (, )di versioni . Ovvero, è consentita qualsiasi versione della dipendenza. Il valore di * non è consentito per la range proprietà .

Deprecazione del pacchetto

Ogni deprecazione del pacchetto ha le proprietà seguenti:

Nome Digita Obbligatorio Note
Motivi matrice di stringhe yes I motivi per cui il pacchetto è stato deprecato
messaggio string no Dettagli aggiuntivi su questa deprecazione
alternatePackage object no Pacchetto alternativo da usare invece

La reasons proprietà deve contenere almeno una stringa e deve contenere solo stringhe della tabella seguente:

Motivo Descrizione
Legacy Il pacchetto non viene più gestito
CriticalBugs Il pacchetto presenta bug che lo rendono non adatto per l'utilizzo
Altro Il pacchetto è deprecato a causa di un motivo non incluso nell'elenco

Se la reasons proprietà contiene stringhe che non provengono dal set noto, devono essere ignorate. Le stringhe non fanno distinzione tra maiuscole e minuscole, quindi legacy devono essere considerate uguali a Legacy. Non esiste alcuna restrizione di ordinamento sulla matrice, quindi le stringhe possono essere disposte in qualsiasi ordine arbitrario. Inoltre, se la proprietà contiene solo stringhe che non provengono dal set noto, deve essere considerata come se conteneva solo la stringa "Other".

Pacchetto alternativo

L'oggetto pacchetto alternativo ha le proprietà seguenti:

Nome Digita Obbligatorio Note
id string yes ID del pacchetto alternativo
range object no Intervallo di versioni consentito o * se è consentita una versione

Vulnerabilità

Matrice di oggetti vulnerability. Ogni vulnerabilità ha le proprietà seguenti:

Nome Digita Obbligatorio Note
advisoryUrl string yes Posizione dell'avviso di sicurezza per il pacchetto
severity string yes Gravità dell'avviso: "0" = Basso, "1" = Moderato, "2" = Alto, "3" = Critico

Esempio di richiesta

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

Assicurarsi di recuperare l'URL di base (https://api.nuget.org/v3/registration-sample/ in questo esempio) dall'indice del servizio, come indicato nella sezione URL di base.

Risposta di esempio

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

In questo caso specifico, l'indice di registrazione ha la pagina di registrazione inlined in modo che non siano necessarie richieste aggiuntive per recuperare i metadati relativi alle singole versioni del pacchetto.

Pagina di registrazione

La pagina di registrazione contiene le foglie di registrazione. L'URL per recuperare una pagina di registrazione è determinato dalla @id proprietà nell'oggetto pagina di registrazione indicato in precedenza. L'URL non deve essere prevedibile e deve essere sempre individuato tramite il documento di indice.

Avviso

In nuget.org, l'URL del documento della pagina di registrazione contiene in modo casuale il limite inferiore e superiore della pagina. Tuttavia, questo presupposto non deve mai essere effettuato da un client poiché le implementazioni del server sono libere di modificare la forma dell'URL purché il documento di indice abbia un collegamento valido.

Quando la items matrice non viene specificata nell'indice di registrazione, una richiesta HTTP GET del @id valore restituirà un documento JSON con un oggetto come radice. Di seguito sono elencate le proprietà dell'oggetto :

Nome Digita Obbligatorio Note
@id string yes URL della pagina di registrazione
numero integer yes Numero di foglie di registrazione nella pagina
articoli matrice di oggetti yes Matrice di foglie di registrazione e dei relativi metadati associati
lower string yes La versione più bassa di SemVer 2.0.0 nella pagina (inclusa)
parent string yes URL dell'indice di registrazione
upper string yes Versione più alta di SemVer 2.0.0 nella pagina (inclusa)

La forma degli oggetti foglia di registrazione corrisponde a quella dell'indice di registrazione precedente.

Esempio di richiesta

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

Assicurarsi di recuperare l'URL di base (https://api.nuget.org/v3/registration-sample/ in questo esempio) dall'indice del servizio, come indicato nella sezione URL di base.

Risposta di esempio

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

Foglia di registrazione

La foglia di registrazione contiene informazioni su un ID pacchetto e una versione specifici. I metadati relativi alla versione specifica potrebbero non essere disponibili in questo documento. I metadati del pacchetto devono essere recuperati dall'indice di registrazione o dalla pagina di registrazione (individuata usando l'indice di registrazione).

L'URL per recuperare una foglia di registrazione viene ottenuto dalla @id proprietà di un oggetto foglia di registrazione in una pagina di registrazione o registrazione. Come per il documento della pagina. l'URL non deve essere prevedibile e deve essere sempre individuato tramite l'oggetto pagina di registrazione.

Avviso

In nuget.org, l'URL del documento foglia di registrazione contiene in modo casuale la versione del pacchetto. Tuttavia, questo presupposto non deve mai essere effettuato da un client perché le implementazioni del server sono libere di modificare la forma dell'URL purché il documento padre abbia un collegamento valido.

La foglia di registrazione è un documento JSON con un oggetto radice con le proprietà seguenti:

Nome Digita Obbligatorio Note
@id string yes URL della foglia di registrazione
catalogEntry string no URL della voce del catalogo che ha prodotto queste foglia
disponibili boolean no Deve essere considerato come elencato se assente
packageContent string no URL del contenuto del pacchetto (.nupkg)
published string no Stringa contenente un timestamp ISO 8601 di quando il pacchetto è stato pubblicato
registrazione string no URL dell'indice di registrazione

Nota

In nuget.org, il valore viene impostato sull'anno published 1900 quando il pacchetto non è elencato.

Esempio di richiesta

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

Assicurarsi di recuperare l'URL di base (https://api.nuget.org/v3/registration-sample/ in questo esempio) dall'indice del servizio, come indicato nella sezione URL di base.

Risposta di esempio

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