Ricerca

È possibile cercare i pacchetti disponibili in un'origine del pacchetto usando l'API V3. La risorsa usata per la ricerca è la SearchQueryService risorsa presente nell'indice del servizio.

Versionamento

Vengono usati i valori seguenti @type :

SearchQueryService/3.5.0

Questa versione introduce il supporto per il packageType parametro di query e la packageTypes proprietà di risposta, consentendo il filtro in base ai tipi di pacchetto definiti dall'autore. È completamente compatibile con le versioni precedenti con le query su SearchQueryService.

URL di base

L'URL di base per l'API seguente è il valore della @id proprietà associata a uno dei valori di risorsa indicati 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.

Cercare pacchetti

L'API di ricerca consente a un client di eseguire query per una pagina di pacchetti corrispondente a una query di ricerca specificata. L'interpretazione della query di ricerca (ad esempio, la tokenizzazione dei termini di ricerca) è determinata dall'implementazione del server, ma l'aspettativa generale è che la query di ricerca viene usata per la corrispondenza di ID pacchetto, titoli, descrizioni e tag. È anche possibile prendere in considerazione altri campi di metadati del pacchetto.

Un pacchetto non elencato non dovrebbe mai essere visualizzato nei risultati della ricerca.

GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}&packageType={PACKAGETYPE}

Parametri della richiesta

La query di q ricerca viene analizzata in modo definito dall'implementazione del server. nuget.org supporta il filtro di base per un'ampia gamma di campi. Se non viene specificato alcun valore q , tutti i pacchetti devono essere restituiti entro i limiti imposti da skip e take. In questo modo viene abilitata la scheda "Sfoglia" nell'esperienza di Visual Studio NuGet.

Per impostazione predefinita, il skip parametro è 0.

Il take parametro deve essere un numero intero maggiore di zero. L'implementazione del server può imporre un valore massimo.

Se prerelease non viene specificato, i pacchetti non definitive vengono esclusi.

Il semVerLevel parametro di query viene usato per acconsentire esplicitamente ai pacchetti SemVer 2.0.0. Se questo parametro di query viene escluso, verranno restituiti solo i pacchetti con versioni compatibili con SemVer 1.0.0 (con le avvertenze standard di controllo delle versioni di NuGet , ad esempio stringhe di versione con 4 parti intere). Se semVerLevel=2.0.0 viene specificato, verranno restituiti i pacchetti compatibili SemVer 1.0.0 e SemVer 2.0.0. Per altre informazioni, vedere il supporto di SemVer 2.0.0 per nuget.org .

Il packageType parametro viene usato per filtrare ulteriormente i risultati della ricerca solo per i pacchetti con almeno un tipo di pacchetto corrispondente al nome del tipo di pacchetto. Se il tipo di pacchetto specificato non è un tipo di pacchetto valido come definito dal documento Tipo di pacchetto, verrà restituito un risultato vuoto. Se il tipo di pacchetto specificato è vuoto, non verrà applicato alcun filtro. In altre parole, il passaggio di nessun valore al parametro packageType si comporta come se il parametro non fosse passato.

risposta

La risposta è un documento JSON contenente fino ai risultati della take ricerca. I risultati della ricerca vengono raggruppati in base all'ID pacchetto.

L'oggetto JSON radice ha le proprietà seguenti:

Risultati della ricerca

Ogni elemento nella data matrice è un oggetto JSON costituito da un gruppo di versioni del pacchetto che condividono lo stesso ID pacchetto. Di seguito sono elencate le proprietà dell'oggetto :

In nuget.org, un pacchetto verificato è uno che ha un ID pacchetto corrispondente a un prefisso ID riservato e di proprietà di uno dei proprietari del prefisso riservato. Per altre informazioni, vedere la documentazione sulla prenotazione del prefisso ID.

I metadati contenuti nell'oggetto risultato della ricerca provengono dalla versione più recente del pacchetto. Ogni elemento nella versions matrice è un oggetto JSON con le proprietà seguenti:

Obsolescenza del pacchetto

L'oggetto deprecation ha le proprietà seguenti:

La reasons matrice contiene almeno uno dei valori documentati in Deprecazione pacchetto.

L'oggetto alternatePackage ha le proprietà seguenti:

Vulnerabilità

Ogni elemento nella vulnerabilities matrice è un oggetto JSON con le proprietà seguenti:

La matrice è vuota quando la versione più recente del pacchetto non presenta vulnerabilità note.

La packageTypes matrice sarà sempre costituita da almeno un elemento (1). Il tipo di pacchetto per un DETERMINATO ID pacchetto viene considerato come i tipi di pacchetto definiti dalla versione più recente del pacchetto rispetto agli altri parametri di ricerca. Ogni elemento nella packageTypes matrice è un oggetto JSON con le proprietà seguenti:

Esempio di richiesta

GET https://search-sample.nuget.org/query?q=NuGet.Versioning&prerelease=false&semVerLevel=2.0.0

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

Risposta di esempio

{
  "totalHits": 2,
  "data": [
    {
      "registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.json",
      "id": "NuGet.Versioning",
      "version": "4.4.0",
      "description": "NuGet's implementation of Semantic Versioning.",
      "summary": "",
      "title": "NuGet.Versioning",
      "licenseUrl": "https://raw.githubusercontent.com/NuGet/NuGet.Client/dev/LICENSE.txt",
      "tags": [ "semver", "semantic", "versioning" ],
      "authors": [ "NuGet" ],
      "totalDownloads": 141896,
      "verified": true,
      "vulnerabilities": [],
      "packageTypes": [
        {
          "name": "Dependency"
        }
      ],
      "versions": [
        {
          "version": "3.3.0",
          "downloads": 50343,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/3.3.0.json"
        },
        {
          "version": "3.4.3",
          "downloads": 27932,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/3.4.3.json"
        },
        {
          "version": "4.0.0",
          "downloads": 63004,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.0.0.json"
        },
        {
          "version": "4.4.0",
          "downloads": 617,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.4.0.json"
        }
      ]
    },
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/index.json",
      "@type": "Package",
      "registration": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/index.json",
      "id": "Nerdbank.GitVersioning",
      "version": "2.0.41",
      "description": "Stamps your assemblies with semver 2.0 compliant git commit specific version information and provides NuGet versioning information as well.",
      "summary": "Stamps your assemblies with semver 2.0 compliant git commit specific version information and provides NuGet versioning information as well.",
      "title": "Nerdbank.GitVersioning",
      "licenseUrl": "https://raw.githubusercontent.com/AArnott/Nerdbank.GitVersioning/ed547462f7/LICENSE.txt",
      "projectUrl": "http://github.com/aarnott/Nerdbank.GitVersioning",
      "tags": [ "git", "commit", "versioning", "version", "assemblyinfo" ],
      "authors": [ "Andrew Arnott" ],
      "totalDownloads": 11906,
      "verified": false,
      "vulnerabilities": [],
      "versions": [
        {
          "version": "1.6.35",
          "downloads": 10229,
          "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/1.6.35.json"
        },
        {
          "version": "2.0.41",
          "downloads": 1677,
          "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/2.0.41.json"
        }
      ]
    }
  ]
}