Vai al contenuto principale
Nota bene Abbiamo rilasciato un nuovo strumento di conformità per X API v2 chiamato batch compliance. Questo nuovo strumento consente di caricare ampi dataset di Post o id utente per recuperare il relativo stato di conformità e determinare quali dati richiedono azioni per portare i tuoi dataset in conformità.
Inoltre, sia il batch compliance sia il compliance firehose sono stati aggiornati per supportare le modifiche ai Post. Per il compliance firehose è stato aggiunto un nuovo evento “tweet_edit”. Consulta la documentazione Compliance Data Objects per maggiori dettagli. Scopri di più su come funziona la metadata di Edit Post nella pagina Edit Posts fundamentals.

​
Panoramica

Enterprise Uno dei valori fondamentali di X è difendere e rispettare la voce degli utenti. Ciò include il rispetto delle loro aspettative e intenzioni quando eliminano, modificano o apportano modifiche ai contenuti che scelgono di condividere su X. Riteniamo che questo sia di importanza cruciale per la salute a lungo termine di una delle più grandi piattaforme pubbliche di informazione in tempo reale al mondo. X mette i controlli nelle mani dei suoi utenti, dando a ciascuno la possibilità di gestire la propria esperienza su X. Riteniamo che le aziende che ricevono dati da X abbiano la responsabilità di rispettare le aspettative e le intenzioni degli utenti finali. Per ulteriori informazioni sui tipi di eventi di conformità possibili sulla piattaforma X, consulta il nostro articolo Honoring User Intent on X. Qualsiasi sviluppatore o azienda che utilizzi i dati di X tramite un’API ha l’obbligo di compiere ogni sforzo ragionevole per rispettare le modifiche ai contenuti degli utenti. Questo obbligo si estende a eventi dell’utente come eliminazioni, modifiche e cambiamenti delle opzioni di condivisione (ad es., contenuti che diventano protetti o non disponibili). Ciò include anche i casi in cui gli utenti modificano i loro Post. Consulta la formulazione specifica nella Developer Policy e/o nel tuo X Data Agreement per comprendere come questo obbligo influisca sul tuo utilizzo dei dati di X. X offre le seguenti soluzioni che forniscono informazioni su questi eventi di conformità degli utenti e indicano se un determinato Post o utente è pubblicamente disponibile o meno. Di seguito è riportata una breve panoramica delle soluzioni e dei relativi schemi di integrazione:

​
GET statuses/lookup e GET users/lookup

  • Formato: API REST. Vedi: GET statuses/lookup e GET users/lookup.
  • Questi endpoint restituiscono sempre la versione più recente di qualsiasi modifica a un Post. Tutti gli Oggetti Post che descrivono Post creati dopo l’introduzione della funzionalità di modifica includeranno i metadati di modifica del Post. Questo vale anche per i Post che non sono stati modificati.
  • Per tutti i Post, le richieste relative a Post a più di 30 minuti dalla loro creazione rappresenteranno lo stato finale di tutti i Post.
  • Forniscono informazioni sulla disponibilità per specifici Post o utenti, come definito dal chiamante nell’ambito della richiesta API.
  • Possono essere utilizzati per verifiche puntuali ad hoc sullo stato di disponibilità corrente di un gruppo specifico di Post/utenti.
  • Ideale per i clienti che necessitano di un modo per verificare lo stato corrente di uno specifico Post o utente in un dato momento.
  • Queste API forniscono un meccanismo utile che può essere utilizzato dai clienti che devono verificare la disponibilità di un contenuto, ad esempio quando:
    1. Si visualizzano Post
    2. Si interagisce in modalità 1:1 con un Post o un utente
    3. Si distribuiscono Contenuti X a terze parti tramite un download di file consentito
    4. Si archiviano Post per periodi di tempo prolungati

​
Compliance Firehose (solo Enterprise)

  • Formato: Streaming API. Vedi: Compliance Firehose.
  • Fornisce uno stream in tempo reale delle attività di compliance su X. Queste attività includono l’editing dei Post.
  • Può essere utilizzato per mantenere lo stato di conformità su un insieme di dati archiviati man mano che sulla piattaforma si verificano nuovi eventi di compliance.
  • Ideale per i clienti che acquisiscono e archiviano grandi volumi di dati di X per periodi prolungati.

​
Guide

​
Best practice per la conformità

​
Raccomandazioni e best practice

  • Progettare schemi di archiviazione che memorizzino l’ID numerico del Post e l’ID utente: I messaggi dell’utente richiedono interventi su tutti i Post di quell’utente. Poiché tutti i messaggi di compliance sono forniti solo tramite ID numerico, è importante progettare schemi di archiviazione che mantengano la relazione tra Post e utente basata su ID numerici. I fruitori di dati dovranno monitorare gli eventi di compliance sia per ID del Post sia per ID utente e poter aggiornare di conseguenza l’archivio dati locale.
  • Progettare schemi che contemplino tutti gli stati di compliance: A seconda di come le attività di compliance verranno gestite nelle varie applicazioni, potrebbe essere necessario aggiungere altra metadata all’archivio dati. Ad esempio, i fruitori di dati potrebbero decidere di aggiungere metadata a un database esistente per facilitare la limitazione della visualizzazione dei contenuti nei Paesi interessati da un messaggio status_withheld.
  • Gestione delle eliminazioni dei Retweet: I Retweet sono un tipo speciale di Post in cui il messaggio originale è annidato in un oggetto all’interno del Retweet. In questo caso, in un Retweet sono presenti due ID del Post: l’ID del Retweet e l’ID del messaggio originale (incluso nell’oggetto annidato). Quando un messaggio originale viene eliminato, viene emesso un messaggio di eliminazione del Post per l’ID originale. Gli eventi di eliminazione del Post in genere attivano eventi di DELETE per tutti i Retweet. Tuttavia, in alcuni casi non tutti vengono inviati e i sistemi client dovrebbero tollerare eliminazioni di Retweet incomplete. L’eliminazione dell’ID originale dovrebbe essere sufficiente per eliminare tutti i Retweet successivi. È una best practice fare riferimento all’ID del Post originale quando si archiviano i Retweet ed eliminare tutti i Retweet referenziati quando si ricevono eventi di eliminazione del Post.

​
Oggetti di dati di conformità

​
Compliance Firehose API

I possibili tipi di eventi di conformità includono eventi relativi ai Post (o “status”) ed eventi relativi agli utenti, per i quali sono descritti di seguito più tipi.   Nota bene:
  • Ulteriori informazioni sugli status utente sono disponibili qui e la nostra policy per sviluppatori sui Post eliminati è consultabile qui.
  • La Compliance Firehose è stata aggiornata per fornire eventi ‘tweet_edit’. 
  • Diversi eventi di eliminazione, protezione e sospensione dell’utente non sono necessariamente permanenti e possono alternarsi tra stati all’infinito. Questi includono: user_delete, user_undelete, user_protect, user_unprotect e user_suspend, user_unsuspend.
  • Gli user_delete sono seguiti da status_delete 30 giorni dopo solo se l’utente non ha scelto di user_undelete il proprio account. È possibile che uno user_delete venga annullato dall’utente e che le eliminazioni di tutti i loro Post dopo 30 giorni non avvengano.
  • user_suspend è un’azione che rimane valida a meno che l’utente non sia soggetto a un evento user_unsuspend. Questi non sono soggetti ad alcuna modifica nel periodo di 30 giorni.
Consulta la colonna ‘Azione consigliata’ per capire come elaborare ciascun tipo di evento al fine di rispettare la privacy e l’intento dell’utente finale.
Tipo di messaggio originaleOggettoPermanente (Sì/No)Azione consigliata
deleteStatusSìElimina il Post associato.
status_withheldStatusSìSopprimi il Post associato nei Paesi specifici elencati nel messaggio status_withheld.
dropStatusNoRimuovi il Post dalla visualizzazione pubblica.
undropStatusNoLo status può essere nuovamente visualizzato e trattato come pubblico.
tweet_editStatusSìRispetta e, ove pertinente, mostra la nuova modifica.
user_deleteUserNoSopprimi o elimina tutti i Post dell’utente associato.
user_undeleteUserNoTutti i Post dell’utente associato possono essere nuovamente visualizzati e trattati come pubblici.
user_protectUserNoSopprimi o elimina tutti i Post dell’utente associato.
user_unprotectUserNoTutti i Post dell’utente associato possono essere nuovamente visualizzati e trattati come pubblici.
user_suspendUserNoSopprimi o elimina tutti i Post dell’utente associato.
user_unsuspendUserNoTutti i Post dell’utente associato possono essere nuovamente visualizzati e trattati come pubblici.
scrub_geoUserSìElimina tutti i geodati forniti da X per tutti i Post dell’utente precedenti al Post specificato nel messaggio scrub_geo. Nota che i Post successivi di un utente possono contenere geodati che possono essere utilizzati.
user_withheldUserSìSopprimi i Post dell’utente associato nei Paesi specifici elencati nel messaggio user_withheld.
deleteFavoriteSìElimina il like/favorite associato.

​
Esempi di payload

Consulta gli esempi di payload riportati di seguito per ciascun evento di compliance descritto nella tabella precedente. Modifica del Post 
{"tweet_edit":
   {
     "id": "1557445923210514432"
     "initial_tweet_id": "1557433858676740098",
     "edit_tweet_ids": ["1557433858676740098", "1557445923210514432"],
     "timestamp_ms": "1660155761384"
   }
 }
Eliminazione di Post
{
  "delete": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220608",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}
Post limitato
{
  "status_withheld": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220608",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "withheld_in_countries": [
      "XY"
    ],
    "timestamp_ms": "1432228155593"
  }
}
Drop
{
  "drop": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220600",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}
Annulla eliminazione
{
  "undrop": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220600",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}

​
Rimuovi dati geografici

{
  "scrub_geo": {
    "user_id": 519761961,
    "up_to_status_id": 411552403083628540,
    "up_to_status_id_str": "411552403083628544",
    "user_id_str": "519761961",
    "timestamp_ms": "1432228180345"
  }
}
Eliminazione dell’utente
{
  "user_delete": {
    "id": 771136850,
    "timestamp_ms": "1432228153548"
  }
}
Ripristino dell’utente
{
  "user_undelete": {
    "id": 796250066,
    "timestamp_ms": "1432228149062"
  }
}
Utente nascosto
{
  "user_withheld": {
    "user": {
      "id": 1375036644,
      "id_str": "1375036644"
    },
    "withheld_in_countries": [
      "XY"
    ],
    "timestampMs": "2014-08-27T23:49:41.839+00:00"
  }
}
Protezione dell’utente
{
  "user_protect": {
    "id": 3182003550,
    "timestamp_ms": "1432228177137"
  }
}
Rimozione protezione utente
{
  "user_unprotect": {
    "id": 2911076065,
    "timestamp_ms": "1432228180113"
  }
}
Sospensione dell’utente
{
  "user_suspend": {
    "id": 3120539094,
    "timestamp_ms": "1432228194217"
  }
}
Riattivazione utente
{
  "user_unsuspend": {
    "id": 3293130873,
    "timestamp_ms": "1432228193828"
  }
}

​
integrazione di Compliance Firehose

La Compliance Firehose è un’API di streaming in tempo reale che recapita eventi di conformità che si verificano sulla piattaforma X. Per comprendere gli eventi di conformità e come vengono generati su X, consulta il nostro articolo Honoring User Intent on X. È importante notare che gli eventi relativi a Post e utenti vengono consegnati separatamente e ciascuno deve essere elaborato indipendentemente (cioè l’eliminazione di un Post non implica un evento utente e viceversa). Diversi eventi utente non sono necessariamente permanenti e possono alternare stato indefinitamente. Questi includono: user_delete, user_undelete, user_protect, user_unprotect e user_suspend, user_unsuspend. Gli user_delete sono seguiti da status_delete 30 giorni dopo solo se l’utente non ha scelto di user_undelete il proprio account. È possibile che uno user_delete venga annullato dall’utente e che, di conseguenza, le eliminazioni di tutti i suoi Post dopo 30 giorni non avvengano. Lo user_suspend è un’azione che rimane valida a meno che l’utente non sia soggetto a un evento user_unsuspend. Questi non subiscono alcuna modifica entro un periodo di 30 giorni. Non è mai opportuno mostrare direttamente gli eventi di conformità agli utenti del tuo software o integrarli nei tuoi prodotti o nelle esperienze dei clienti. Sono destinati esclusivamente al mantenimento della conformità e al rispetto delle azioni degli utenti di X.

​
Integrazione con il Compliance Firehose

Per integrare il Compliance Firehose nel tuo sistema, devi creare un’integrazione in grado di svolgere le seguenti operazioni:
  1. Stabilire una connessione in streaming a ciascuna partizione dell’API di streaming del Compliance Firehose
  2. Gestire volumi elevati di data – disaccoppiare l’acquisizione dello stream dall’elaborazione aggiuntiva utilizzando processi asincroni
  3. Riconnettersi automaticamente alle partizioni dello stream quando la connessione viene interrotta per qualsiasi motivo
  4. Elaborare gli eventi di compliance pertinenti ai Post e ai dati utente che hai archiviato, in conformità con le linee guida presentate sopra

​
Rispettare le intenzioni degli utenti su X

Riteniamo che rispettare la privacy e le intenzioni degli utenti di X sia fondamentale per la salute a lungo termine di una delle più grandi piattaforme pubbliche di informazioni in tempo reale al mondo. X affida i controlli sulla privacy ai suoi utenti, dando a ciascuno la possibilità di gestire la propria esperienza su X. In quanto aziende che utilizzano i dati di X, abbiamo la responsabilità collettiva di rispettare la privacy e le azioni degli utenti finali per mantenere un ambiente di fiducia e rispetto. Sulla piattaforma possono verificarsi varie azioni che interessano i Post e gli account utente e che influiscono sulla loro visualizzazione. Le azioni che riguardano privacy e intenzioni sono definite sia a livello di Status (Post) sia a livello di Utente. Queste azioni includono:

​
Utente

AzioneDescrizione
Proteggi accountUn utente di X può proteggere o rimuovere la protezione dal proprio account in qualsiasi momento. Gli account protetti richiedono l’approvazione manuale, da parte dell’utente, di ogni persona autorizzata a visualizzare i Post del proprio account. 
Per ulteriori informazioni, vedi Informazioni su Post pubblici e protetti.
Elimina accountUn utente di X può decidere di eliminare il proprio account e tutti i messaggi di stato associati in qualsiasi momento. X conserva le informazioni dell’account per 30 giorni dopo l’eliminazione, nel caso in cui l’utente decida di annullare l’eliminazione e riattivare il proprio account.
Rimozione dati di localizzazioneUn utente di X può rimuovere in qualsiasi momento tutti i dati di localizzazione dai Post passati. Questa operazione è nota come “scrub geo”.
Sospendi accountX si riserva il diritto di sospendere gli account che violano le Regole di X o se si sospetta che un account sia stato violato o compromesso. Le sospensioni dell’account possono essere revocate (unsuspend) solo da X.
Limitazione per paese dell’accountX si riserva il diritto di limitare reattivamente, di volta in volta, l’accesso a determinati contenuti in un paese specifico. Un account sottoposto a limitazione può essere rimosso dalla limitazione solo da X. 
Per ulteriori informazioni, vedi Contenuti limitati per paese.

​
Stato

AzioneDescrizione
Elimina statoUn utente X può eliminare uno stato in qualsiasi momento. Gli stati eliminati non possono essere ripristinati e vengono eliminati in modo permanente.
Limitare statoX si riserva il diritto di limitare, in modo reattivo, l’accesso a determinati contenuti in uno specifico paese di volta in volta. Uno stato limitato può essere reso di nuovo disponibile solo da X. 
Per ulteriori informazioni, consulta Contenuti limitati per paese.

​
Monitorare le modifiche a Utente e Status

Lo stato di un Utente o di uno Status può cambiare in qualsiasi momento a seguito di una delle azioni sopra indicate, e questo influisce su come i consumatori dei dati di X devono gestire la disponibilità e la privacy di tutti i contenuti associati. Quando queste azioni si verificano, viene inviato un messaggio di compliance corrispondente che indica che lo stato di un Utente o di uno Status è cambiato.

​
Riferimento API

​
GET compliance/firehose

​
Metodi

MetodoDescrizione
GET /compliance/:streamConnessione allo stream di dati

​
Autenticazione

Tutte le richieste alla Compliance Firehose API devono utilizzare l’autenticazione HTTP Basic, derivata da una combinazione valida di indirizzo email e password usata per accedere al tuo account su console.gnip.com. Le credenziali devono essere inviate nell’header Authorization per ogni richiesta.

​
GET /compliance/:stream

Stabilisce una connessione persistente al firehose di dati di Compliance, attraverso la quale verranno recapitati gli eventi di compliance.
Request MethodHTTP GET
Connection TypeKeep-Alive
URLDisponibile nella pagina di aiuto dell’API dello stream nel tuo dashboard e ha una struttura simile alla seguente:


https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1

Nota: il parametro “partition” è obbligatorio. Dovrai connetterti a tutte e 8 le partition, ciascuna contenente il 12,5% del volume totale, per consumare l’intero stream.
CompressionGzip. Per connetterti allo stream utilizzando la compressione Gzip, invia un header Accept-Encoding nella richiesta di connessione. L’header dovrebbe essere il seguente:

Accept-Encoding: gzip
Character EncodingUTF-8
Response FormatJSON. L’header della richiesta dovrebbe specificare il formato JSON per la risposta.
Rate Limit10 richieste ogni 60 secondi.
Read TimeoutImposta un timeout di lettura sul client e assicurati che sia superiore a 30 secondi.
Support for Tweet editsTutte le modifiche ai Tweet generano un evento di Compliance “tweet_edit”. Consulta la documentazione Compliance Data Objects per maggiori dettagli.
Example Curl Request La seguente richiesta di esempio è eseguita utilizzando cURL dalla riga di comando: 
curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1"
Nota: la richiesta sopra si connette solo a partition=1 del Compliance firehose: dovrai connetterti a tutte e 8 le partition per consumare l’intero stream.

​
Codici di risposta

Le seguenti risposte possono essere restituite dall’API per queste richieste. La maggior parte dei codici di errore è accompagnata nel body da una stringa con dettagli aggiuntivi. Per risposte diverse da 200, i client dovrebbero tentare di riconnettersi.
StatoTestoDefinizione
200SuccessoLa connessione è stata aperta correttamente e le nuove attività verranno inviate man mano che arrivano.
401Non autorizzatoL’autenticazione HTTP non è riuscita a causa di credenziali non valide. Accedi a console.gnip.com con le tue credenziali per verificare di utilizzarle correttamente nella richiesta.
406Non accettabileIn genere si verifica quando il client non include correttamente gli header per accettare la codifica gzip dallo stream, ma può verificarsi anche in altre circostanze. Conterrà un messaggio JSON simile a “Questa connessione richiede la compressione. Per abilitare la compressione, invia l’header ‘Accept-Encoding: gzip’ nella richiesta ed esegui la decompressione dello stream mentre viene letto lato client.”
429Limite di velocità superatoLa tua App ha superato il limite per le richieste di connessione.
503Servizio non disponibileProblema del server X. Riconnettiti utilizzando un backoff esponenziale. Se non è stato pubblicato alcun avviso su questo problema sulla X API Status Page, contatta il supporto.

​
Altre raccomandazioni e best practice

  • Progetta schemi di archiviazione dei dati che memorizzino l’ID numerico del Tweet e l’ID dell’utente: I messaggi relativi agli utenti richiedono azioni su tutti i Tweet di quell’utente. Poiché tutti i messaggi di conformità vengono recapitati esclusivamente tramite ID numerici, è importante progettare schemi di archiviazione che mantengano la relazione tra Tweet e Utente basata su ID numerici. Chi utilizza i dati dovrà monitorare gli eventi di conformità sia per ID del Tweet sia per ID dell’utente ed essere in grado di aggiornare correttamente l’archivio dati locale.
  • Progetta schemi che contemplino tutti gli stati di conformità: A seconda di come le attività di conformità verranno gestite nelle diverse applicazioni, potrebbe essere necessario aggiungere ulteriore metadata all’archivio dati. Ad esempio, chi utilizza i dati può decidere di aggiungere metadata a un database esistente per facilitare la limitazione della visualizzazione dei contenuti nei paesi interessati da un messaggio status_withheld.
  • Gestione delle eliminazioni dei Retweet: I Retweet sono un tipo particolare di Tweet in cui il messaggio originale è annidato in un oggetto all’interno del Retweet. In questo caso, in un Retweet sono presenti due ID di Tweet: l’ID del Retweet e l’ID del messaggio originale (incluso nell’oggetto annidato). Quando il messaggio originale viene eliminato, viene emesso un messaggio di eliminazione del Tweet per l’ID originale. Successivi messaggi di delete NON vengono emessi per tutti i Retweet. L’eliminazione dell’ID originale dovrebbe essere sufficiente per eliminare tutti i Retweet successivi.
⌘I