> This page is for Piattaforma, version Versione precedente. > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 sperimentale: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Versione precedente: https://next.developer.frame.io/platform/v2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # Cerca risorse # Panoramica L'API di Frame.io consente di cercare in modo approfondito e variegato le risorse in un intero account, rispecchiando le funzionalità dell'applicazione web. I filtri più utili di solito sono quelli per team, progetto e stato, ma filtri e ordinamento possono essere combinati in modi unici per produrre set di risultati molto specifici grazie all'API. In genere, tutti i filtri oltre a `account_id`, `q` (query) e `sort` seguono la stessa struttura e sono spiegati tutti di seguito. search-filters.png Esiste un bug che influisce sulla funzione di paginazione dell'API di ricerca (almeno fino a marzo 2022). Fino a quando questo bug non viene risolto, sconsigliamo di usare l'API di ricerca per scorrere più pagine di risultati (cioè più di 100 risorse), poiché la dimensione della pagina richiesta potrebbe non corrispondere al numero effettivo di risorse restituite. ## Valori predefiniti La richiesta API per attivare una ricerca è sempre la stessa: È sempre la stessa richiesta `POST` a `https://api.frame.io/v2/search/library` Se non forniti esplicitamente, i valori predefiniti per l'ottimizzazione della ricerca sono i seguenti: | Attributo | Valore predefinito | Descrizione | |:--------|:------------|:----------| | `page_size` | 10 | Verranno restituite 10 risorse per pagina. | | `page` | 1 | La query restituirà la prima pagina della risposta. | | `sort` | `relevance` | "relevance" tenta di ordinare le risorse basandosi su un set di attributi specificatamente ottimizzato. In assenza di una query, la rilevanza è orientata fortemente verso la prossimità temporale ("recency") del caricamento. | ## Informazioni su questa guida Questa guida descrive il processo di creazione di una query di ricerca per trovare una corrispondenza a questi criteri: * Risorse all'interno di un account * Corrisponde alla query `"moon"` * È in un progetto specifico * È stata caricata tra il 1° e il 30 aprile 2020 * Ed è stata "approvata" Il corpo della nostra ricerca avrà questo aspetto: ```json { "account_id": "", "q": "moon", "sort": "name", "filter": { "inserted_at": [ { "op": "gte", "value": "2020-04-01T04:00:00.000Z" }, { "op": "lte", "value": "2020-04-30T03:59:59.999Z" } ], "project_id": { "op": "eq", "value": "" }, "label": { "op": "eq", "value": "approved" } }, "page_size": 10, "page": 1 } ``` ### Account, query e ordinamento L'account (`account_id`), la query (`q`) e l'ordinamento (`sort`) sono i tre elementi di base che si trovano al di fuori di qualsiasi attributo `filter` in una query di ricerca. #### Contesto dell'account Tecnicamente, l'unico attributo necessario per eseguire una ricerca è un `account_id`. In questo modo vengono richiamate semplicemente tutte le risorse (incluse le cartelle) nell'account con i valori di paginazione predefiniti (10 risorse per pagina, a partire dalla pagina 1). ```json { "account_id": "" } ``` #### Query di ricerca Il successivo attributo più comune (e utile) da includere è la query stessa. Nota: poiché la ricerca dell'API Frame.io accetta una query nulla, non è necessaria una query con carattere jolly (`*`). L'operazione riguarda la ricerca di qualcosa o l'ordinamento (potenzialmente filtrato) di tutte le risorse in un account. Nel nostro caso, cercheremo il termine "moon". ```json { "account_id": "", "q": "moon" } ``` ### Ordinamento sort.png Frame.io supporta diverse opzioni di ordinamento. La sintassi per il tipo di ordinamento è simile tra le varie opzioni: * C'è una direzione di ordinamento predefinita * Per invertire quella direzione, aggiungi come prefisso il segno meno (`-`) al valore di ordinamento Ad esempio, per ordinare in ordine alfabetico inverso (da Z ad A), usa `"sort": "-name"`. L'operazione di ordinamento predefinita si basa sulla "Rilevanza". Di conseguenza, non è necessario dichiararla e sarà presunta se non viene fornito alcun attributo `sort`. | Opzione di ordinamento | Attributo | Direzione predefinita | |:----------|:--------|:----------------| | **Rilevanza** | n/a | n/a | | **Data di caricamento** | `inserted_at` | Prima il meno recente | | **Nome** | `name` | Da A a Z | | **Dimensione** | `filesize` | Prima il più piccolo | | **Autore caricamento** | `creator.name` | Da A a Z | Di conseguenza, durante la creazione della query, possiamo aggiungere l'ordinamento (`sort`) in base al nome (`name`), dalla A alla Z: ```json { "account_id": "", "q": "moon", "sort": "name" } ``` ### Filtri e paginazione I filtri sono sia la funzionalità più complicata che quella più potente della ricerca delle risorse di Frame.io. I filtri vengono scritti all'interno di un singolo oggetto `filter` e seguono tutti lo stesso modello con un'operazione (`op`) e un valore (`valore`). I filtri utilizzeranno le seguenti abbreviazioni comuni. Le opzioni di equivalenza diverse da "uguale a" sono riservate alle query relative a data e dimensioni: * `eq` -- uguale a * `lt` -- minore di * `gt` -- maggiore di * `lte` -- minore o uguale a * `gte` -- maggiore o uguale a * `match` -- corrispondenza esatta, utilizzato solo per i filtri per l'autore del caricamento e il tipo di file Ad esempio, un filtro (`filter`) per trovare una corrispondenza con un `project_id` noto verrebbe costruito come segue: ```json { "filter": { "project_id": { "op": "eq", "value": "" } } } ``` ### Opzioni e operazioni La seguente tabella descrive le opzioni e le operazioni associate a ciascun tipo di filtro. | Opzione di filtro | Attributo | Operazioni supportate | Valori supportati | |:------------|:--------|:-------------------|:---------------| | **Archiviato** | `archived` | `eq` | `true`, `false` | | **Data di caricamento** | `inserted_at` | `eq`, `lt`, `gt`, `lte`, `gte` | `<datetime>` (ISO-8601, UTC) | | **Eliminato** | `deleted` | `eq` | `true`, `false` | | **Tipo di file** | `filetype` | `match` | `` | | **Privato** | `private` | `eq` | `true`, `false` | | **Progetto** | `project_id` | `eq` | `<project_id>` | | **Dimensione** | `filesize` | `eq`, `lt`, `gt`, `lte`, `gte` | `size` (in byte) | | **Stato** | `label` | `eq` | `none`, `in_progress`, `needs_review`, `approved` | | **Team** | `id_team` | `eq` | `<team_id>` | | **Tipo** | `asset_type` | `eq` | `audio`, `document`, `folder`, `image`, `other`, `stream`, `video` | | **Autore caricamento** | `creator.name` | `match` | `<name>` | La ricerca di un creatore che non è più membro dell'account non funzionerà, poiché tale utente non è più nell'indice di ricerca degli utenti. Per continuare a creare la query, ora possiamo aggiungere un filtro per le risorse che corrispondono a questi criteri: * È in un progetto specifico * È stata caricata tra il 1° e il 30 aprile 2020 * È contrassegnata come "Approvata" ```json { "account_id": "", "q": "moon", "sort": "name", "filter": { "inserted_at": [ { "op": "gte", "value": "2020-04-01T04:00:00.000Z" }, { "op": "lte", "value": "2020-04-28T03:59:59.999Z" } ], "project_id": { "op": "eq", "value": "" }, "label": { "op": "eq", "value": "approved" } } } ``` L'endpoint di ricerca esegue la paginazione esattamente come qualsiasi altro endpoint tramite gli attributi `page_size` e `page` che si trovano al livello più esterno del corpo della richiesta. Per maggiori dettagli sulla paginazione, consulta la guida a parte [qui](/platform/v2/key-concepts#pagination).