Come posso limitare il numero di chiamate API / righe aggiornate in un'istruzione UPDATE?

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;