# SearchRefinements

> **Traduzione italiana non ufficiale.** Originale: [SearchRefinements](https://affiliate-program.amazon.com/creatorsapi/docs/en-us/api-reference/resources/search-refinements) · [sorgente EN](../../../en/api-reference/resources/search-refinements.md) · [indice](../../../README.md)

La risorsa `searchRefinements` può essere richiesta per ottenere SearchIndex, BrowseNode e refinement dinamici per una richiesta di ricerca. La risorsa è rilevante solo per l'operazione [SearchItems](../operations/search-items.md).

## Disponibilità

Tutti i locale. Tuttavia, i vari refinement restituiti differiscono in base al locale.

## Funzionalità

Le categorie/sottocategorie di ricerca pertinenti e i refinement dinamici restituiti come parte della risorsa `searchRefinements` possono essere usati per affinare la richiesta di ricerca. Se richiesta, la risorsa SearchRefinements restituisce:

* I SearchIndex pertinenti quando la richiesta di ricerca è nel SearchIndex `"All"`. Usa i SearchIndex pertinenti restituiti per lanciare una richiesta di ricerca successiva in un SearchIndex specifico. Nota che le ricerche in una categoria mirata (cioè diversa da "All") restituiscono prodotti più pertinenti. La risorsa SearchRefinements ti aiuta a trovare il search index più pertinente per la tua richiesta. Per l'elenco dei SearchIndex, vedi [Riferimento dei locale](../../locale-reference.md).
* I BrowseNodeId pertinenti quando la richiesta di ricerca è in una categoria diversa da "All". Usa il BrowseNodeId pertinente per lanciare una richiesta successiva in una sottocategoria specifica e affinare ulteriormente l'ambito della ricerca ottenendo risultati migliori.
* I refinement dinamici (se applicabili) restituiti per ogni richiesta di ricerca. Per esempio, se la richiesta è nel SearchIndex Books e il marketplace Amazon di destinazione supporta i refinement per autore, riceverai nomi di autori pertinenti come refinement dinamici.

## Elementi di risposta

Ogni elemento di risposta è incapsulato in un contenitore Refinement che contiene i dettagli sull'ID del refinement, il nome visualizzato e il valore del refinement. Per maggiori informazioni, vedi Contenitore Refinement.

| Nome | Descrizione |
| :--- | :--- |
| SearchIndex | Contenitore dei SearchIndex pertinenti per una richiesta di ricerca. Include il valore del SearchIndex e il suo nome visualizzato. Il valore del SearchIndex può essere usato per lanciare una richiesta successiva in una categoria di ricerca specifica. Per maggiori informazioni, vedi [Elemento di risposta SearchIndexes](#elemento-di-risposta-searchindexes) |
| BrowseNode | Contenitore delle informazioni dinamiche sui BrowseNode per una particolare richiesta di ricerca. Include l'elenco dei BrowseNodeID e i loro nomi visualizzati. Il BrowseNodeID può essere usato per lanciare una richiesta successiva in una sottocategoria specifica. Per maggiori informazioni, vedi [Elemento di risposta BrowseNodes](#elemento-di-risposta-browsenodes) |
| OtherRefinements | Contenitore dei refinement dinamici per una richiesta di ricerca, che include l'ID (che è anche un parametro di richiesta dell'operazione SearchItems) e i bins. Per maggiori informazioni, vedi [Elemento di risposta OtherRefinements](#elemento-di-risposta-otherrefinements) |

#### Contenitore Refinement

Questo è un contenitore generico per tutti i tipi di refinement forniti dalla risorsa `searchRefinements`. Un contenitore refinement all'interno della risorsa `searchRefinements` appare così:

```json
{
  "searchRefinements": {
    "refinementType": {
      "id": "Nome del parametro di SearchItems",
      "displayName": "Nome visualizzato del parametro",
      "bins": [
         /* Valori del refinement per il RefinementType */
        {
           "id": "Il valore effettivo del refinement",
           "displayName": "Nome visualizzato del valore del refinement"
        }
      ]
    }
  }
}
```

> [!NOTE]
> I RefinementType sono i vari [elementi di risposta](#elementi-di-risposta) (SearchIndex/BrowseNode/ecc.) restituiti dalla risorsa SearchRefinements.

La tabella seguente descrive brevemente i vari attributi all'interno del contenitore Refinement:

| Nome attributo | Descrizione |
| :--- | :--- |
| Id | L'`Id` indica a quale parametro di richiesta di [SearchItems](../operations/search-items.md) si lega un particolare refinement. Per esempio, per un refinement `BrowseNode`, l'`Id` sarà `BrowseNodeId`. |
| DisplayName | Il nome visualizzato del parametro di refinement sul sito Amazon, che varia in base al locale. Per esempio, il DisplayName per un refinement `BrowseNode` sarà `Department` nel locale USA. |
| Bins | I bins contengono i valori validi per il refinement. I bins sono a loro volta un contenitore di `Id` e `DisplayName`, dove `Id` contiene il valore effettivo del refinement usabile per lanciare una richiesta successiva. Per esempio, `Id` e `DisplayName` per un refinement `BrowseNode` possono essere rispettivamente `344520001` e `Women's Clothing`. Qui, la richiesta successiva può essere lanciata fornendo `{ "BrowseNodeId": "344530001" }` nella richiesta. |

#### Elemento di risposta SearchIndexes

La struttura dell'elemento SearchIndexes all'interno della risorsa `searchRefinements` appare così:

```json
{
  "searchRefinements": {
    "searchIndex": {
      "id": "SearchIndex",
      "displayName": "Department",
      "bins": [
        {
          "id": "AppsAndGames",
          "displayName": "Apps and Games"
        },
        {
          "id": "DigitalMusic",
          "displayName": "Digital Music"
        }
        /* Altri SearchIndex pertinenti */
      ]
    }
  }
}
```

I SearchIndex sono restituiti per ogni richiesta di ricerca nel SearchIndex `"All"`. Usa il SearchIndex pertinente per restringere la richiesta a una categoria specifica. Dall'esempio sopra, se **Digital Music** sembra la categoria pertinente per la tua ricerca, lancia una richiesta successiva con `DigitalMusic` come `SearchIndex`.

#### Elemento di risposta BrowseNodes

La struttura dell'elemento BrowseNodes all'interno della risorsa `searchRefinements` appare così:

```json
{
  "searchRefinements": {
    "browseNode": {
      "id": "BrowseNodeId",
      "displayName": "Department",
      "bins": [
        {
          "id": "344520001",
          "displayName": "Women Clothing"
        },
        {
          "id": "2233000134",
          "displayName": "Men Clothing"
        }
        /* Altri BrowseNodeId pertinenti */
      ]
    }
  }
}
```

I BrowseNode sono restituiti per ogni richiesta di ricerca che si trova in un search index specifico, cioè diverso da "All". Usa il BrowseNodeId pertinente per restringere la richiesta a una sottocategoria specifica. Dall'esempio sopra, se **Women Clothing** sembra la sottocategoria pertinente per la tua ricerca, lancia una richiesta successiva con `344520001` come `BrowseNodeId`.

#### Elemento di risposta OtherRefinements

La struttura dell'elemento OtherRefinements all'interno della risorsa `searchRefinements` appare così:

```json
{
 "searchRefinements": {
  "otherRefinements": [
    {
     "id": "Brand",
     "displayName": "Brand",
     "bins": [
        {
         "id": "Sony",
         "displayName": "Sony"
        },
        {
         "id": "Sony",
         "displayName": "Sony"
        }
      ]
    },
    {
      /* Altri refinement dinamici (se disponibili) */
    }
  ]
 }
}
```

Gli OtherRefinements sono restituiti per ogni richiesta di ricerca all'interno di un search index specifico, se la combinazione di search index e marketplace supporta un particolare refinement. Usa il `Bin Id` per lanciare una richiesta successiva affinando i risultati. Al momento, la risorsa SearchRefinements restituisce valori dinamici per i seguenti (se disponibili in un particolare SearchIndex e marketplace):

* Actor
* Artist
* Author
* Brand

> [!NOTE]
> Ci possono essere casi in cui ottieni un certo refinement come risposta ma lo stesso non funziona quando lanci la richiesta successiva. Per esempio, potresti ottenere il refinement `Artist` nelle ricerche della categoria `DigitalMusic`, ma quando usi il filtro `Artist` potresti ottenere `NoResults`. In questi casi, usa i valori del refinement in `keywords` per ottenere i risultati desiderati.

## Richieste e risposte di esempio

Gli esempi seguenti mostrano i casi d'uso di SearchRefinements.

#### Esempio 1

L'esempio mostra il comportamento della risorsa SearchRefinements quando una richiesta di ricerca nel marketplace USA è nella categoria "All".

##### Richiesta:

```json
{
   "partnerTag": "xyz-20",
   "itemCount": 1,
   "keyword": "Harry Potter",
   "resources" : [ "searchRefinements" ]
}
```

##### Risposta:

```json
{
  "searchResult": {
    "items": [
      {
        "asin": "0545162076",
        "detailPageURL": "https://www.amazon.com/dp/0545162076?tag=dgfd&linkCode=osi&th=1&psc=1"
      }
    ],
    "searchRefinements": {
      "searchIndex": {
        "id": "SearchIndex",
        "displayName": "Department",
        "bins": [
          { "id": "Books", "displayName": "Books" },
          { "id": "MoviesAndTV", "displayName": "Movies & TV" },
          { "id": "Fashion", "displayName": "Clothing, Shoes & Jewelry" },
          { "id": "HomeAndKitchen", "displayName": "Home & Kitchen" },
          { "id": "Beauty", "displayName": "Beauty & Personal Care" }
          /* Altri SearchIndex pertinenti */
        ]
      }
    },
    "searchURL": "https://www.amazon.com/s/?field-keywords=Harry+Potter&search-alias=aps&tag=xyz-20&linkCode=osi",
    "totalResultCount": 146
  }
}
```

Nota che i search index più pertinenti sono in cima. Cioè, in questo esempio, il search index Books è il più pertinente.

#### Esempio 2

L'esempio mostra il comportamento della risorsa SearchRefinements quando una richiesta di ricerca per la keyword "Mystery Novels" nel marketplace USA è nella categoria "Books".

##### Richiesta:

```json
{
   "partnerTag": "xyz-20",
   "itemCount": 1,
   "keyword": "Mystery Novels",
   "searchIndex": "Books",
   "resources" : [ "searchRefinements" ]
}
```

##### Risposta:

```json
{
  "searchResult": {
    "items": [
      {
        "asin": "1683993039",
        "detailPageURL": "https://www.amazon.com/dp/1683993039?tag=dgfd&linkCode=osi&th=1&psc=1"
      }
    ],
    "searchRefinements": {
      "browseNode": {
        "id": "BrowseNodeId",
        "displayName": "Department",
        "bins": [
          { "id": "17", "displayName": "Literature & Fiction" },
          { "id": "18", "displayName": "Mystery, Thriller & Suspense" },
          { "id": "23", "displayName": "Romance" }
          /* Altri BrowseNode pertinenti */
        ]
      },
      "otherRefinements": [
        {
          "displayName": "Author",
          "id": "Author",
          "bins": [
            { "id": "Agatha Christie", "displayName": "Agatha Christie" },
            { "id": "Arthur Conan Doyle", "displayName": "Arthur Conan Doyle" },
            { "id": "Wilkie Collins", "displayName": "Wilkie Collins" }
            /* Altri autori pertinenti */
          ]
        }
      ]
    },
    "searchURL": "https://www.amazon.com/s/?field-keywords=Mystery+Novels&search-alias=stripbooks&tag=xyz-20&linkCode=osi",
    "totalResultCount": 1200
  }
}
```
