Invantive SQL rende semplice l’aggiornamento e la sincronizzazione massiva dei dati, poiché la tecnica rimane sotto il cofano. Con l’istruzione update e/o l’istruzione synchronize è possibile aggiornare facilmente in massa i dati nelle applicazioni cloud, in modo che tutti i vostri processi aziendali utilizzino gli stessi dati.
Alcune applicazioni cloud limitano, per motivi tecnici, di fair use e/o commerciali, il numero di chiamate API. Spesso, al superamento del limite, viene restituito un messaggio di errore come “Too many requests” oppure un codice di stato HTTP 429.
Il termine comunemente usato per indicare una tale limitazione delle chiamate API è “rate limit”. A volte si applicano più rate limit contemporaneamente, ad esempio al giorno, al mese, al minuto, per API, per operazione API (lettura/scrittura) o per risultato API: con o senza messaggio di errore.
Spesso è possibile acquistare chiamate API aggiuntive per aumentare il rate limit, sia con pagamento anticipato che con fatturazione posticipata. Su alcune piattaforme, l’ampliamento del rate limit delle chiamate API a limiti più alti/aggiuntivi è relativamente costoso, con picchi fino a diverse decine di euro per chiamata nel caso di chiamate complesse; su altre piattaforme è invece estremamente economico.
È consigliabile utilizzare lo spazio disponibile nei rate limit delle chiamate API nei momenti giusti, quando i numeri sono limitati per unità di tempo come il mese o il giorno. Le modifiche a bassa priorità vanno eseguite alla fine del periodo per ottenere il massimo rendimento dal vostro investimento nella piattaforma cloud.
Variate il numero di chiamate API nel tempo solo dopo aver prima limitato il numero di chiamate API; suggerimenti funzionali a riguardo sono disponibili su Hoe plan ik mijn Exact Online-omgeving op het beschikbare aantal API-calls? e suggerimenti tecnici, ad esempio, su Snel en met minder API-calls Exact Online uitlezen met de incrementele "sync API"-tabellen.
Invantive SQL offre strumenti per utilizzare nel modo più efficace possibile lo spazio disponibile nei rate limit delle chiamate API. Lo spazio disponibile è visibile, nella maggior parte delle piattaforme, nelle colonne della vista del dizionario dati SystemPartitions@DataDictionary. In essa sono presenti colonne per i rate limit giornalieri, orari e al minuto, e per il numero di richieste effettuate nel giorno, nell’ora e nel minuto correnti.
Per l’istruzione synchronize è possibile specificare il numero massimo di modifiche da eseguire. Questo è possibile anche con le tradizionali istruzioni SQL update, delete e insert.
Il numero massimo di modifiche per update, delete, insert può essere impostato tramite limit NUMERO, proprio come limit limita il numero di righe restituite da una selezione tramite select.
Questo viene illustrato tramite un caso pratico con l’API di Exact Online.
Caso: Modifica degli Allegati delle Fatture
Nel sistema di contabilità Exact Online è possibile impostare, per ogni relazione all’interno di un’amministrazione, in quali formati vengono inviate le fatture. Si può trattare di una combinazione di formati, che vengono combinati in un numero tramite il cosiddetto “bitwise AND”. Il valore “1”, ad esempio, significa solo fatture di vendita in formato PDF, il valore “2” significa formato UBL e il valore “3” significa sia formato PDF che UBL.
In un database Exact Online con amministrazioni contenenti ciascuna 50.000 relazioni, il formato degli allegati delle fatture deve essere convertito, per tutte le amministrazioni, da PDF più UBL a solo PDF. Tuttavia, il numero di chiamate API al giorno su Exact Online è solo una frazione delle 50.000 chiamate API necessarie, e la conversione ha una priorità inferiore rispetto alle elaborazioni giornaliere.
Per questo motivo, le modifiche vengono effettuate alla fine della giornata su Exact Online, per consumare l’eventuale budget di chiamate API rimanente con queste richieste aggiuntive.
La priorità più alta riguarda questa modifica per i clienti di vendita; le altre relazioni non hanno ancora lo status di cliente.
Nel job, il numero di modifiche su Exact Online può essere limitato a 10 tramite il seguente update:
use SELECTIE_ADMINISTRATIES@eol
update exactonlinerest..accounts@eol
set InvoiceAttachmentType = 1
where InvoiceAttachmentType = 3
and status = 'C'
limit 100
Notate che in questo caso non viene utilizzata la tabella Exact Online AccountsIncremental; questa è di sola lettura e richiederebbe un’istruzione synchronize più complessa, mentre la clausola where, grazie al filtraggio lato server di Invantive e al filtro di Exact Online, può essere passata direttamente a Exact Online, rendendo necessaria una sola chiamata API di Exact Online per recuperare le righe da aggiornare.
Questa istruzione, se ci sono ancora clienti per i quali è necessaria una modifica, sarà completata dopo circa 3 secondi.
Un eventuale budget residuo di chiamate API può essere utilizzato per impostare il tipo di allegato della fattura anche per i non clienti:
use SELECTIE_ADMINISTRATIES@eol
update exactonlinerest..accounts@eol
set InvoiceAttachmentType = 1
where InvoiceAttachmentType = 3
limit 100
Approfondimento: più amministrazioni
La modifica massiva può essere facilmente estesa a più amministrazioni. A tal fine, specificate prima la selezione delle amministrazioni, ad esempio per tutte le amministrazioni Exact Online:
use all@eol
update exactonlinerest..accounts@eol
set InvoiceAttachmentType = 1
where InvoiceAttachmentType = 3
and status = 'C'
limit 1000
update exactonlinerest..accounts@eol
set InvoiceAttachmentType = 1
where InvoiceAttachmentType = 3
limit 1000
Poiché attualmente su Exact Online i limiti API si applicano per amministrazione, è possibile impostare il limite più alto. In questo esempio si parte da 10 amministrazioni, dove le 1000 modifiche verranno distribuite approssimativamente in modo uniforme su tutte e 10 grazie all’elaborazione parallela, a meno che la quantità di aggiornamenti API necessari per amministrazione non vari in modo significativo.
Approfondimento: solo lo spazio libero per le chiamate API nel minor tempo possibile
Un affinamento più avanzato consiste nel limitare il numero di chiamate API alla quantità disponibile per un’amministrazione, minimizzando al contempo i tempi di esecuzione (senza parallelizzazione).
Il seguente blocco Invantive PSQL avvia di volta in volta brevi sequenze di aggiornamenti, con una lunghezza scelta in modo tale che il limite al minuto di Exact Online di 60 chiamate API al minuto venga raggiunto il più rapidamente possibile:
declare
l_did_work boolean;
l_dummy_cnt number;
g_max_call_per_minute pls_integer := 50 /* Leggermente inferiore a 60 per poter cambiare più spesso. */;
begin
use all@eol;
--
-- Assicuratevi che i numeri relativi alle chiamate API rimanenti siano aggiornati
-- toccando brevemente tutte le amministrazioni.
--
select /*+ http_disk_cache(false) http_memory_cache(false) */ count(*)
into l_dummy_cnt
from exactonlinerest..journals@eol
;
l_did_work := true;
while l_did_work
loop
dbms_output.put_line('Tentativo di raggiungere i limiti al minuto delle chiamate API per amministrazione durante un minuto.');
l_did_work := false;
for r
in
( select 'update exactonlinerest..accounts@eol'
|| ' set InvoiceAttachmentType = 1'
|| ' where InvoiceAttachmentType = 3'
|| ' limit '
|| to_char
( case
when DAILY_REMAINING > g_max_call_per_minute
then g_max_call_per_minute
else DAILY_REMAINING
--
-- Lasciate 500 chiamate API di Exact Online disponibili
-- per priorità impreviste più avanti nella giornata.
--
- 500
end
)
stmt
, 'Aggiorna al massimo '
|| g_max_call_per_minute
|| ' righe nell\'amministrazione '
|| code
|| ' - '
|| name
txt
from SYSTEMPARTITIONS@DataDictionary
where IS_SELECTED = true
and PROVIDER_NAME = 'ExactOnlineAll'
and PROVIDER_DATA_CONTAINER_ALIAS = 'eol'
--
-- Devono rimanere ancora almeno 500 chiamate API
-- oggi per questa amministrazione.
--
and DAILY_REMAINING > 500
)
loop
dbms_output.put_line(r.txt);
execute immediate r.stmt;
l_did_work := true;
end loop;
end loop;
end;