Gestire le richieste del data store Open Cloud

Ci sono diverse considerazioni riguardo l'invio di richieste e la gestione delle risposte dalle API del data store Open Cloud.

Intestazioni HTTP

Come tutti gli endpoint Open Cloud, le richieste al data store che utilizzano l'autenticazione con chiave API devono includere l'intestazione x-api-key. Per ulteriori informazioni, vedere Gestire le chiavi API.

• Un'API key errata o mancante genera un errore 401.
• Un'API key valida che manca delle corrette autorizzazioni genera un errore 403.

Se una richiesta include un corpo, come una richiesta di creazione o aggiornamento, includere le intestazioni Content-Type: application/json e Content-Length. La maggior parte dei client include automaticamente queste intestazioni.

Pagina

I data store spesso contengono molte voci, il che significa che il tuo codice, in particolare quando chiama Elenca le voci del data store, deve gestire un numero massimo di risultati e pagine. Per saperne di più, vedere Paginazione.

Filtri

Se usi prefissi nei nomi delle voci del tuo data store, probabilmente vuoi filtrare le tue chiamate GET, in questo modo:

def list_entries(universe, data_store, filter):
    list_path = f'universes/{universe}/data-stores/{data_store}/entries'
    url = base_url + list_path
    return requests.get(url, params={'filter': f'id.startsWith("global/{filter}")'}, headers={apiHeaderKey: apiKey})

La sintassi dei filtri è estremamente limitata. Vedi la documentazione di riferimento per i filtri disponibili per i data store standard e ordinati.

Consenti flag mancanti

I metodi PATCH (aggiornamento) per i data store standard e ordinati hanno un parametro allow_missing. Se impostato su true, questo parametro consente di creare voci che non esistono già anziché generare un errore. Lascia questo parametro al suo valore predefinito di false a meno che tu non abbia una buona ragione per non farlo; aggiornare una voce che non è mai stata creata rappresenta spesso un errore nella logica di programmazione.

Scope

Molte richieste richiedono di specificare uno scope, anche se è il valore predefinito di global. Questi scope sono distinti dagli scope di autorizzazione e ti consentono di suddividere e organizzare le voci in un data store.

Tuttavia, piuttosto che creare scope non predefiniti, raccomandiamo vivamente di utilizzare prefissi. Per saperne di più, vedere Elenco e prefissi.

Content-MD5

L'API Open Cloud v1 supporta un checksum MD5 codificato in base64 opzionale in alcune richieste, che può rilevare problemi di integrità dei dati. Molti linguaggi hanno funzioni incorporate per calcolare il valore dell'intestazione content-md5. Il seguente esempio utilizza Python:

$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"
sTf90fedVsft8zZf6nUg8g==

Se riscontri problemi a generare un valore content-md5 valido, potresti dover codificare il corpo della tua richiesta in UTF-8 prima di calcolare il checksum.