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.

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:

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:

1
{
2
    "account_id": "<account_id>",
3
    "q": "moon",
4
    "sort": "name",
5
    "filter": {
6
        "inserted_at": [
7
            {
8
                "op": "gte",
9
                "value": "2020-04-01T04:00:00.000Z"
10
            },
11
            {
12
                "op": "lte",
13
                "value": "2020-04-30T03:59:59.999Z"
14
            }
15
        ],
16
        "project_id": {
17
            "op": "eq",
18
            "value": "<project_id>"
19
        },
20
        "label": {
21
            "op": "eq",
22
            "value": "approved"
23
        }
24
    },
25
    "page_size": 10,
26
    "page": 1
27
}

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).

1
{
2
    "account_id": "<account_id>"
3
}

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”.

1
{
2
    "account_id": "<account_id>",
3
    "q": "moon"
4
}

Ordinamento

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.

1
{
2
    "account_id": "<account_id>",
3
    "q": "moon",
4
    "sort": "name"
5
}

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:

1
{
2
    "filter": {
3
        "project_id": {
4
            "op": "eq",
5
            "value": "<project_id>"
6
        }
7
    }
8
}

Opzioni e operazioni

La seguente tabella descrive le opzioni e le operazioni associate a ciascun tipo di filtro.

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”

1
{
2
    "account_id": "<account_id>",
3
    "q": "moon",
4
    "sort": "name",
5
    "filter": {
6
        "inserted_at": [
7
            {
8
                "op": "gte",
9
                "value": "2020-04-01T04:00:00.000Z"
10
            },
11
            {
12
                "op": "lte",
13
                "value": "2020-04-28T03:59:59.999Z"
14
            }
15
        ],
16
        "project_id": {
17
            "op": "eq",
18
            "value": "<project_id>"
19
        },
20
        "label": {
21
            "op": "eq",
22
            "value": "approved"
23
        }
24
    }
25
}