Primi passi con l'API unificata per i dati: dal catalogo delle funzionalità al primo risultato utilizzabile

Scrivere il codice delle richieste per una sola piattaforma di solito è semplice. I veri attriti iniziano con la seconda piattaforma: i nomi dei parametri cambiano, gli identificatori di utenti e contenuti sono diversi, alcuni endpoint restituiscono subito i dati mentre altri creano prima un task. Quando partono i cron job, logica dei nuovi tentativi, deduplicazione e riconciliazione degli addebiti sviluppano ciascuna un proprio percorso di codice.

L'API unificata per i dati elimina questo lavoro di integrazione ridondante. In EveryData di EveryInfra usi la stessa autenticazione Bearer, scegli la piattaforma con platform, la funzionalità con action e passi i parametri specifici della funzionalità in params. A essere unificati sono il punto di chiamata e il flusso di gestione generale; i dati delle piattaforme non vengono forzati in un unico oggetto di business.

Questo tutorial mostra una richiesta minima con la ricerca di note su Xiaohongshu, poi spiega come estenderla ad altre funzionalità. L'obiettivo non è solo eseguire una singola richiesta HTTP, ma fare in modo che il tuo programma sappia quali dati ha recuperato, quali risultati sono ancora in sospeso e come il run successivo deve colmare la lacuna. Gli esempi si basano su cataloghi pubblici e implementazioni verificati al 2026-09-04; gli snippet POST di produzione sono modelli di chiamata per scenari consentiti, non successi live misurati di recente.

Prima stabilisci se ti serve recuperare dati o cercare e generare

Se sai già a quale piattaforma appartiene ciò che ti interessa (ad esempio una nota specifica, un prodotto o un luogo) e vuoi leggerne i campi strutturati, l'API per i dati è il punto di partenza giusto. Se invece ti stai ancora chiedendo dove si trovino online i materiali, parti dalla ricerca web; se i materiali li hai già e ti servono riepiloghi, classificazioni o la stesura di report, usa l'elaborazione con i modelli.

Prendiamo l'analisi dei commenti: la raccolta dice cosa sono questi commenti e da dove provengono, mentre i modelli dicono quali problemi emergono da questi testi. I modelli non possono inventare record mancanti a causa di errori di raccolta, né interpretare come zero i conteggi di commenti non restituiti. Separare le due fasi ti permette di tornare alle prove originali quando una conclusione è contestata, invece di dover ricostruire per ipotesi l'intera catena di chiamate.

Passaggio 1: conferma le funzionalità dal catalogo, non indovinare gli endpoint dai nomi delle piattaforme

Il catalogo delle funzionalità si può leggere senza chiave API. Usa prima la versione compatta per capire quali piattaforme e azioni sono disponibili, poi recupera il riferimento completo di parametri e campi per la piattaforma scelta. La vista compatta serve alla scoperta e omette le descrizioni di parametri e campi: non usarla come validatore completo delle richieste.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?compact=1' \
  | jq '.capabilities[] | {platform, action, required_params, mode, available}'

Per esempio, per trovare note di Xiaohongshu legate a una parola chiave di ricerca, consulta prima search; se hai già il link di una nota e ti servono dettagli o commenti, scegli rispettivamente note o comments. Nomi simili non significano che siano intercambiabili: le parole chiave di ricerca non si possono passare direttamente come URL nelle richieste di dettaglio.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=xiaohongshu' \
  | jq -e '.capabilities[] | select(.action == "search") | {
      platform, action, required_params, optional_params,
      param_meanings, mode, returns_list,
      default_limit, max_limit, response_fields, available
    }'

In questa verifica del catalogo, il parametro obbligatorio di xiaohongshu.search è keyword, con mode impostato su sync e returns_list su true; il count predefinito è 20, con un limite massimo di 50. Questi ultimi due valori descrivono le impostazioni di quantità di questa funzionalità, non una garanzia di consegna per richiesta né un limite universale tra piattaforme. Il catalogo elenca anche sort e content_type; quando filtri, usa i valori consentiti indicati in param_meanings e non copiare le enumerazioni di un'altra piattaforma.

• required_params: input obbligatori. Soddisfali prima di aggiungere filtri uno alla volta.
• param_meanings: definizioni dei parametri e valori consentiti dichiarati. Non inventare enumerazioni personalizzate per campi non elencati.
• mode e returns_list: indicano se serve il polling del task e se i dati di business finali sono un elenco o un singolo oggetto.
• response_fields: serve a pianificare la mappatura dei campi; non è una risposta live né garantisce che ogni campo abbia un valore non vuoto.
• available: flag di disponibilità a livello di catalogo; non dimostra in anticipo che un URL target restituirà dati in questo momento.

Le funzionalità che restituiscono elenchi supportano anche il parametro generico limit, che potrebbe non comparire in optional_params. Questa distinzione è verificata dal codice di validazione delle richieste. In fase di integrazione, esamina insieme dichiarazioni dell'elenco, valori predefiniti/limiti e descrizioni complete; non eliminare parametri limit validi solo perché un confronto di stringhe con optional_params non li trova.

Passaggio 2: invia una richiesta abbastanza piccola da ispezionare facilmente

Prepara una chiave API con i permessi adeguati per la funzionalità e passala tramite le variabili d'ambiente del server. Non inserirla nel codice frontend del browser, negli screenshot o in file di esempio scaricabili pubblicamente. Gli esempi qui sotto presuppongono che EVERYINFRA_API_KEY sia configurata con il tuo sistema di gestione dei secret; i comandi inviano una singola richiesta senza nuovi tentativi automatici.

: "${EVERYINFRA_API_KEY:?set the server-side API Key first}"
curl --silent --show-error --include --max-time 180 \
  'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{
    "platform": "xiaohongshu",
    "action": "search",
    "params": {
      "keyword": "AI tools",
      "limit": 5
    }
  }'

Qui 5 indica la dimensione del piccolo campione che vuoi ottenere, non una garanzia di consegna; 180 secondi è il timeout di attesa del client in questo esempio, non uno SLA del servizio. Verifica campi, formati dei timestamp e link alle fonti con un piccolo set di risultati prima di aumentare i volumi. Durante il primo debug conserva la riga di stato HTTP e il corpo della risposta, così in caso di codici 4xx o 5xx puoi leggere l'errore specifico invece di un generico messaggio di errore di curl.

I tre campi di primo livello vanno tenuti distinti: platform e action scelgono la funzionalità, mentre tutte le condizioni di business vanno in params. Non spostare keyword al primo livello e non aggiungere page, cursor o sort ad azioni che non li supportano. I parametri assenti dal catalogo non si possono dare per supportati solo perché la maggior parte delle API è progettata così.

OpenAPI aiuta persone e programmi a descrivere corpi delle richieste, parametri e risposte, ma non impone modelli di business identici tra piattaforme. Quando generi tipi o costruisci i client, usa le specifiche per capire il formato di descrizione delle interfacce, poi affidati al catalogo e al formato di risposta del servizio per stabilire i campi esatti.

Passaggio 3: capisci la struttura esterna e interna dei risultati sincroni

Per xiaohongshu.search, l'implementazione mette gli elenchi in results, accanto ai metadati esterni id, platform, action, count, billing e quota. L'id esterno è l'identificatore di tracciamento della richiesta, mentre l'id di ogni record in results è l'identificatore del contenuto. Non confonderli: usa il primo per debug e riconciliazione, il secondo per deduplicare i record.

Non considerare results l'unico percorso di lettura per ogni client. Altre azioni possono restituire oggetti di business con nomi diversi; returns_list indica la forma dell'oggetto e i dizionari dei campi spiegano i campi interni, ma nessuno dei due sostituisce la verifica della struttura esterna della funzionalità scelta. Aggiungere una nuova funzionalità richiede una configurazione esplicita di adattamento dei risultati, non una ricerca ricorsiva del primo array in ogni risposta.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/fields?platform=xiaohongshu&action=search' \
  | jq '{fields, undocumented}'

Due dettagli nella gestione dei campi influenzano spesso le conclusioni. Primo: le metriche di engagement null indicano dati non pubblici o non disponibili e non vanno riempite automaticamente con 0 prima di calcolare le medie. Secondo: la documentazione pubblica di posted_at consente di conservare le stringhe di timestamp grezze della piattaforma, quindi non dare per scontato che tutti i valori si convertano direttamente in un unico formato ISO. Salva a parte i timestamp convertiti e conserva un flag di stato per le conversioni non riuscite, invece di assegnare la data di oggi alle date non convertite.

Se le risposte includono i flag partial o missed, i target non consegnati vanno tracciati separatamente: HTTP 200 non garantisce che ogni target di un batch restituisca dati. Da un array vuoto si può concludere solo che questa volta non sono stati restituiti record, non che i dati manchino sulla piattaforma originale. Se le richieste abbiano coperto gli oggetti giusti e rispettato i limiti di ambito è una questione separata.

Passaggio 4: per le funzionalità asincrone attendi lo stato finale, non fermarti al job_id

Quando passi a funzionalità con mode impostato su async, le risposte di invio possono restituire HTTP 202 insieme a status, job_id e poll_url. Salva questi campi prima di iniziare a interrogare il task. Secondo la specifica HTTP, 202 indica che la richiesta è stata accettata ma l'elaborazione non è completa: non usarlo per attivare notifiche di business come «report generato».

: "${EVERYINFRA_API_KEY:?set the API Key used for this task first: API Key}"
: "${EVERYINFRA_JOB_ID:?paste the job_id from the actual submit response}"
curl --silent --show-error --include --max-time 30 \
  "https://api.everyinfra.com/api/v1/jobs/${EVERYINFRA_JOB_ID}" \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}"

Le implementazioni attuali delle query cercano i job in base alla chiave usata al momento dell'invio. Interroga con la stessa chiave e non dare per scontato di poter recuperare il task cambiando chiave nello stesso account; se non lo trovi, non ricreare subito un task identico. Verifica dominio API, job_id e chiavi usati, ricorrendo se necessario alle informazioni di richiesta salvate.

• running o finalizing: stati di elaborazione. Conserva il task e continua il polling a intervalli limitati.
• succeeded: il task raggiunge uno stato finale di successo; analizza l'oggetto dati della funzionalità e verifica i requisiti di business.
• failed: il task raggiunge uno stato finale di errore; leggi error e conserva i record del task senza trattarlo come un successo con dati vuoti.
• Timeout della query o stato sconosciuto: contrassegnalo solo come non confermato. Imposta un budget di attesa totale per i flussi di recupero successivi, senza cambiarlo in successo o fallimento.

I poller devono imporre tempi di attesa massimi con intervalli di backoff crescenti per evitare loop serrati. Al riavvio del programma, riprendi il polling dai job_id salvati invece di reinviare i task. Salva a parte gli addebiti dell'invio: le risposte attuali alle query sui risultati non ripetono il blocco billing completo, quindi l'assenza di billing nei risultati della query non significa addebito zero.

Anche il pattern Asynchronous Request-Reply di Microsoft separa accettazione, controllo dello stato e risultati finali, e tratta i suggerimenti per il polling. È un utile riferimento di design per i flussi lato client; qui EveryInfra non garantisce la restituzione di header come Location e Retry-After, e le query effettive continuano a usare il punto di accesso fornito nella risposta corrente.

Passaggio 5: gestisci gli errori in base alla causa, senza ripetere le POST alla cieca

Gli errori di business richiedono di controllare insieme lo stato HTTP e error.code. Gli attuali punti di accesso ai dati verificano prima l'autenticazione, poi funzionalità, permessi e parametri, prima di passare ai flussi di quota ed esecuzione. Ricevere un 401 senza una chiave valida non conferma che i parametri di business abbiano superato la validazione.

• 401: verifica che la chiave esista, sia valida e che l'header Bearer sia corretto. Non cercare di risolvere un errore di autenticazione modificando le parole chiave.
• 403: verifica che la chiave sia autorizzata per i prodotti e le funzionalità target. I problemi di permessi vanno gestiti dal personale autorizzato, senza cambiare account automaticamente.
• 400 unknown_capability: controlla che platform e action corrispondano; rileggi i cataloghi ed esamina i nomi candidati suggeriti dal servizio.
• 422: controlla campi obbligatori, parametri sconosciuti ed enum non validi. Correggi un errore alla volta prima di inviare nuove richieste.
• 402: quota insufficiente; va risolto il problema del credito dell'account, e ripetere richieste identiche non cambia nulla.
• 429, errori temporanei del servizio o interruzioni di rete: applica un backoff e verifica lo stato della richiesta originale. Riprova con limiti definiti solo dopo aver verificato che sia sicuro.

Il dettaglio più facile da trascurare è il timeout del client quando il server potrebbe aver già accettato la richiesta. Dal punto di vista del business il recupero dei dati sembra un'operazione di sola lettura, ma viene eseguito con POST e può creare task e generare addebiti. Gli ID di correlazione aiutano ad associare più tentativi, ma non forniscono automaticamente garanzie di idempotenza lato server. Non aggiungere header Idempotency-Key senza un supporto esplicito dell'API dando per scontato che le richieste duplicate vengano eseguite una sola volta.

RFC 9110 pone limiti rigidi ai nuovi tentativi automatici per le richieste non idempotenti. In caso di esito sconosciuto, interroga prima i task esistenti o controlla i record delle richieste; quando i dati non bastano, mantenere lo stato sconosciuto è più sicuro che ripetere automaticamente interi batch.

Passaggio 6: salva separatamente dati, stato della raccolta e addebiti

Il vantaggio principale di un punto di accesso unificato è chiarire la divisione dei compiti tra record generici e mappature dei campi delle piattaforme. Mantieni almeno tre tipi di record: un task di business, un tentativo API e un oggetto della piattaforma. Così tieni traccia di quanti tentativi ha richiesto un task e puoi aggiornare lo stesso contenuto in più raccolte senza creare nuovi oggetti duplicati.

• Record dei task: il tuo task_id, l'ambito target, i campi attesi e i criteri di completamento. Qui il completamento è definito dal business, non dal solo successo HTTP.
• Record delle richieste: platform, action, riepiloghi non sensibili dei parametri, orari di inizio/fine, ID delle richieste API, job_id, stato e addebiti. Conserva anche i tentativi falliti.
• Record degli oggetti: piattaforma, tipo di oggetto, id dell'oggetto, link alle fonti, campi effettivamente acquisiti e observed_at; non unire ID che coincidono per caso tra piattaforme diverse.

Si tratta di raccomandazioni per il modello di dati dell'applicazione, non di campi aggiuntivi restituiti da EveryInfra. observed_at va registrato dai collector per indicare il momento dell'osservazione, mentre posted_at indica quando il contenuto originale è stato pubblicato. Usandoli entrambi sai quando un contenuto è stato pubblicato e quando ne hai avuto notizia, e puoi analizzare dati in ritardo e osservazioni ripetute.

Nei confronti tra piattaforme, mappa solo i campi richiesti dal business con semantica confrontabile. Like, salvataggi, valutazioni dei prodotti e conteggi dei commenti sono metriche diverse: rinominarle tutte score non le porta su una scala unica. Per i campi non interpretati, conserva lo stato di mancanza o consulta i dizionari invece di indovinare unità e significati.

Gli addebiti non si ricavano dal numero di elementi nei risultati. Le funzionalità multi-target addebitano per target, quindi la richiesta HTTP non è l'unità di addebito; limiti di campione ridotti non implicano sconti proporzionali sul numero restituito. Le attuali implementazioni sincrone gestiscono i rami di rimborso per risultati vuoti e consegne parziali, ma il tuo client deve salvare gli addebiti effettivi e i movimenti contabili per gli audit; non considerare il conto chiuso solo sulla base di un 200 o di array vuoti.

Quando registri le richieste, prendi come riferimento il design degli ID di interazione di OWASP: correla gli eventi di un singolo intento di business ed escludi elementi sensibili come i token di accesso. Conservare informazioni utili al debug non significa riversare nei log header delle richieste e testo grezzo.

Quale codice conviene riutilizzare quando passi a una seconda piattaforma

Iniezione dell'autenticazione, impostazioni dei timeout, log degli errori, scheduler delle query sui task e log di sicurezza sono riutilizzabili. Devono restare specifici per funzionalità i nomi e la semantica dei parametri, i percorsi degli oggetti nei risultati, le mappature dei campi, le regole di paginazione e i criteri di completamento. Separare le due parti evita che aggiungere funzionalità in futuro diventi un copia-incolla di interi client.

Conviene memorizzare i cataloghi in cache con l'orario di osservazione e riverificarli prima di integrare nuove funzionalità o rilasciare aggiornamenti. Evita cache senza scadenza, ma non scaricare nemmeno il catalogo completo per ogni record: imposta gli intervalli di aggiornamento in base alla tolleranza del business ai cambiamenti e avvia ricontrolli mirati solo in caso di unknown_capability o di parametri non corrispondenti.

Paginazione e incrementi richiedono molta cautela. Procedi solo quando un'azione fornisce esplicitamente parametri di paginazione e segnali di fine; senza di essi, non creare mai cursori lato client. Le query pianificate producono più osservazioni e non equivalgono automaticamente a storici completi o a tutti i nuovi contenuti. I report della prima versione devono indicare esplicitamente i target controllati e le finestre temporali, invece di dichiarare una copertura completa non dimostrabile.

Per quali task questo approccio non è adatto così com'è

Se devi pubblicare per conto degli utenti, gestire profili di merchant, gestire autorizzazioni degli account o modificare dati della piattaforma, consulta le API ufficiali della piattaforma e i relativi flussi di autorizzazione, invece di usare gli endpoint per dati pubblici come interfacce di gestione degli account. Per contenuti privati, dati riservati o casi d'uso non consentiti, gli endpoint unificati non ampliano i tuoi privilegi di accesso.

Anche quando i dati sono visibili pubblicamente, archiviazione, analisi e nuova visualizzazione vanno valutate rispetto alle regole della piattaforma e agli scopi di business specifici. Limita gli ambiti di ricerca ai target e ai campi necessari, controlla i periodi di conservazione ed evita di riportare profili degli autori, link con parametri di accesso o testo grezzo direttamente nei log pubblici. La capacità tecnica di fare una richiesta e il permesso d'uso per il business sono due verifiche distinte.

Parti da un risultato che sai spiegare

Completata l'integrazione iniziale, fatti quattro domande: so indicare con chiarezza la funzionalità specifica che ho chiamato? So ricondurre ogni dato alla sua fonte? So distinguere successo, elaborazione, consegna parziale ed esito sconosciuto? Se le richieste falliscono o si duplicano, so spiegare i record e gli addebiti risultanti?

Quando hai una risposta a tutte e quattro, amplia le piattaforme, aumenta le richieste simultanee e integra l'analisi con i modelli. Il valore delle API unificate per i dati non è far sparire tutte le differenze, ma farti scrivere logica personalizzata solo dove le differenze tra piattaforme esistono davvero. Scegli una funzionalità dalla documentazione qui sotto, verifica piccoli campioni, salva correttamente i risultati e inizia il passo successivo.