Compliance Firehose API

Ten en cuenta

Hemos lanzado una nueva herramienta de cumplimiento para X API v2 llamada batch compliance. Esta nueva herramienta te permite cargar grandes conjuntos de datos de IDs de Publicación o de usuario para recuperar su estado de cumplimiento y así determinar qué datos requieren alguna acción para que tus conjuntos de datos estén en cumplimiento.

Además, tanto batch compliance como compliance firehose se han actualizado para admitir ediciones de Publicaciones. Para compliance firehose, se añadió un nuevo evento “tweet_edit”. Consulta la documentación de Compliance Data Objects para obtener más detalles. Obtén más información sobre cómo funcionan los metadatos de Edit Post en la página Edit Posts fundamentals.

​

Descripción general

Enterprise

Uno de los valores fundamentales de X es defender y respetar la voz de los usuarios. Esto incluye respetar sus expectativas e intención cuando eliminan, modifican o editan el contenido que deciden compartir en X. Consideramos que esto es de importancia crítica para la salud a largo plazo de una de las plataformas públicas de información en tiempo real más grandes del mundo. X pone controles en manos de sus usuarios, otorgando a las personas la capacidad de controlar su propia experiencia en X. Creemos que las empresas que reciben datos de X tienen la responsabilidad de respetar las expectativas y la intención de los usuarios finales.

Para obtener más información sobre los tipos de eventos de cumplimiento posibles en la plataforma de X, consulta nuestro artículo, Respetar la intención del usuario en X.

Todo desarrollador o empresa que consuma datos de X a través de una API tiene la obligación de realizar todos los esfuerzos razonables para respetar los cambios en el contenido de los usuarios. Esta obligación se extiende a eventos de usuario como eliminaciones, modificaciones y cambios en las opciones para compartir (por ejemplo, cuando el contenido pasa a estar protegido o retenido). Esto también incluye cuando los usuarios editan sus Publicaciones. Consulta la redacción específica en la Política para Desarrolladores y/o en tu Acuerdo de Datos de X para entender cómo esta obligación afecta tu uso de los datos de X.

X ofrece las siguientes soluciones que proporcionan información sobre estos eventos de cumplimiento de usuario y sobre si una Publicación o un Usuario específico está disponible públicamente o no. A continuación se ofrece una breve descripción general de las soluciones y sus patrones de integración en términos generales:

​

GET statuses/lookup and GET users/lookup

• Formato: API REST. Consulte: GET statuses/lookup y GET users/lookup.

• Estos endpoints siempre devuelven la versión más reciente de cualquier edición de Publicación. Todos los objetos de Publicación que describen Publicaciones creadas después de que se introdujo la función de edición incluirán metadatos de edición de Publicación. Esto es así incluso para Publicaciones que no fueron editadas.

• Para todas las Publicaciones, las solicitudes de Publicaciones realizadas más de 30 minutos después de su creación representarán el estado final de dichas Publicaciones.

• Ofrecen información de disponibilidad para Publicaciones o Usuarios específicos, según lo definido por quien realiza la llamada como parte de la solicitud de API.

• Se pueden utilizar para comprobaciones puntuales ad hoc sobre el estado de disponibilidad actual de un grupo específico de Publicaciones/Usuarios.

• Son ideales para clientes que necesitan una forma de comprobar el estado actual de una Publicación o Usuario específicos en un momento dado.

• Estas API proporcionan un mecanismo útil que los clientes pueden usar cuando necesitan comprobar la disponibilidad de una pieza de Contenido, por ejemplo, cuando:

  1. Muestran Publicaciones
  2. Interactúan con una(s) Publicación(es) o Usuario(s) de forma 1:1
  3. Distribuyen Contenido de X a un tercero mediante una descarga de archivos autorizada
  4. Almacenan Publicaciones durante períodos prolongados

​

Compliance Firehose (solo para clientes enterprise)

• Formato: API de streaming. Véase: Compliance Firehose.
• Entrega un flujo en tiempo real de actividades de cumplimiento en X. Estas actividades incluyen cuando se editan Publicaciones. 
• Se puede usar para mantener el estado de cumplimiento en un conjunto de datos almacenado a medida que se producen nuevos eventos de cumplimiento en la plataforma.
• Ideal para clientes que consumen y almacenan grandes volúmenes de datos de X durante períodos prolongados.

​

Guías

​

Mejores prácticas de cumplimiento

​

Recomendaciones y mejores prácticas

• Cree esquemas de almacenamiento de datos que almacenen el Post ID numérico y el User ID: Los mensajes de un Usuario requieren que se tomen acciones sobre todas las Publicaciones de ese Usuario. Por lo tanto, dado que todos los mensajes de cumplimiento se entregan solo mediante un ID numérico, es importante diseñar esquemas de almacenamiento que mantengan la relación entre la Publicación y el Usuario basándose en IDs numéricos. Los consumidores de datos deberán supervisar los eventos de cumplimiento tanto por Post ID como por User ID y poder actualizar correctamente el almacén de datos local.

• Cree esquemas que aborden todos los estados de cumplimiento: Dependiendo de cómo se gestionen las actividades de cumplimiento en varias aplicaciones, puede ser necesario agregar otros metadatos al almacén de datos. Por ejemplo, los consumidores de datos pueden decidir agregar metadatos a una base de datos existente para facilitar la restricción de la visualización de contenido en países afectados por un mensaje status_withheld.

• Gestión de borrados de Retweet: Los Retweets son un tipo especial de Publicación en el que el mensaje original está anidado en un objeto dentro del Retweet. En este caso, hay dos Post IDs referenciados en un Retweet: el ID del Retweet y el ID del mensaje original (incluido en el objeto anidado). Cuando se elimina un mensaje original, se emite un mensaje de borrado de Publicación para el ID original. Los eventos de borrado de Publicaciones normalmente desencadenan eventos de borrado para todos los Retweets. Sin embargo, en algunos casos no se envían todos y los sistemas clientes deben ser tolerantes a borrados incompletos de Retweets. La eliminación del ID original debería ser suficiente para borrar todos los Retweets posteriores. Es una buena práctica hacer referencia al Post ID original al almacenar Retweets y eliminar todos los Retweets referenciados al recibir eventos de borrado de Publicaciones.

​

Objetos de datos de cumplimiento

​

API de Compliance Firehose

Los posibles tipos de eventos de cumplimiento incluirán eventos de Publicación (o “estado”) y eventos de Usuario, para los cuales existen múltiples tipos descritos a continuación.  

Tenga en cuenta:

• Lea más sobre los estados de Usuario aquí y sobre nuestra política para desarrolladores en relación con las Publicaciones eliminadas aquí.
• Compliance Firehose se ha actualizado para proporcionar eventos tweet_edit. 
• Varios eventos de eliminación, protección y suspensión de Usuario no son necesariamente permanentes y pueden alternar entre estados indefinidamente. Estos incluyen: user_delete, user_undelete, user_protect, user_unprotect y user_suspend, user_unsuspend.
• Los user_deletes son seguidos por status_deletes 30 días después solo si el usuario no ha elegido user_undelete para recuperar su cuenta. Es posible que un user_delete sea revertido por el usuario y que las eliminaciones de todas sus Publicaciones 30 días después no se produzcan.
• user_suspend es una acción que sigue siendo válida a menos que el usuario esté sujeto a un evento user_unsuspend. Estos no están sujetos a ningún cambio en un período de 30 días.

Consulte la columna ‘Recommended Action’ para comprender cómo procesar cada tipo de evento a fin de respetar la privacidad y la intención del usuario final.

Original Message Type	Object	Permanent (Yes/No)	Recommended Action
delete	Estado	Yes	Elimine la Publicación asociada.
status_withheld	Estado	Yes	Suprima la Publicación asociada en los países específicos indicados en el mensaje status_withheld.
drop	Estado	No	Retire la Publicación de la vista pública.
undrop	Estado	No	El estado puede volver a mostrarse y tratarse como público.
tweet_edit	Estado	Yes	Respete y, cuando corresponda, muestre la nueva edición.
user_delete	Usuario	No	Suprima o elimine todas las Publicaciones del usuario asociado.
user_undelete	Usuario	No	Todas las Publicaciones del usuario asociado pueden volver a mostrarse y tratarse como públicas.
user_protect	Usuario	No	Suprima o elimine todas las Publicaciones del usuario asociado.
user_unprotect	Usuario	No	Todas las Publicaciones del usuario asociado pueden volver a mostrarse y tratarse como públicas.
user_suspend	Usuario	No	Suprima o elimine todas las Publicaciones del usuario asociado.
user_unsuspend	Usuario	No	Todas las Publicaciones del usuario asociado pueden volver a mostrarse y tratarse como públicas.
scrub_geo	Usuario	Yes	Elimine todos los datos geográficos proporcionados por X para todas las Publicaciones del usuario anteriores a la Publicación especificada en el mensaje scrub_geo. Tenga en cuenta que las Publicaciones posteriores de un usuario pueden contener datos geográficos que pueden utilizarse.
user_withheld	Usuario	Yes	Suprima las Publicaciones del usuario asociado en los países específicos indicados en el mensaje user_withheld.
delete	Favorito	Yes	Elimine el like/favorito asociado.

​

Ejemplos de carga útil

Consulta los ejemplos de carga útil a continuación para cada evento de cumplimiento descrito en la tabla anterior.

Edición de publicación

{"tweet_edit":
   {
     "id": "1557445923210514432"
     "initial_tweet_id": "1557433858676740098",
     "edit_tweet_ids": ["1557433858676740098", "1557445923210514432"],
     "timestamp_ms": "1660155761384"
   }
 }

Eliminación de publicación

{
  "delete": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220608",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}

Publicación retenida

{
  "status_withheld": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220608",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "withheld_in_countries": [
      "XY"
    ],
    "timestamp_ms": "1432228155593"
  }
}

Eliminar

{
  "drop": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220600",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}

Revertir eliminación

{
  "undrop": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220600",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}

​

Eliminación de datos de ubicación

{
  "scrub_geo": {
    "user_id": 519761961,
    "up_to_status_id": 411552403083628540,
    "up_to_status_id_str": "411552403083628544",
    "user_id_str": "519761961",
    "timestamp_ms": "1432228180345"
  }
}

Eliminación de usuario

{
  "user_delete": {
    "id": 771136850,
    "timestamp_ms": "1432228153548"
  }
}

Restauración de usuario

{
  "user_undelete": {
    "id": 796250066,
    "timestamp_ms": "1432228149062"
  }
}

Usuario retenido

{
  "user_withheld": {
    "user": {
      "id": 1375036644,
      "id_str": "1375036644"
    },
    "withheld_in_countries": [
      "XY"
    ],
    "timestampMs": "2014-08-27T23:49:41.839+00:00"
  }
}

Proteger usuario

{
  "user_protect": {
    "id": 3182003550,
    "timestamp_ms": "1432228177137"
  }
}

Quitar protección de usuario

{
  "user_unprotect": {
    "id": 2911076065,
    "timestamp_ms": "1432228180113"
  }
}

Suspensión de usuario

{
  "user_suspend": {
    "id": 3120539094,
    "timestamp_ms": "1432228194217"
  }
}

Levantamiento de suspensión de usuario

{
  "user_unsuspend": {
    "id": 3293130873,
    "timestamp_ms": "1432228193828"
  }
}

​

integrating Compliance Firehose

Compliance Firehose es una API de streaming en tiempo real que entrega eventos de cumplimiento que se producen en la plataforma X. Para comprender los eventos de cumplimiento y cómo se generan en X, consulta nuestro artículo, Respetar la intención del usuario en X.

Es importante tener en cuenta que los eventos de Publicación y de Usuario se entregan de manera independiente y que cada uno debe procesarse por separado (es decir, la eliminación de una Publicación no implica un evento de Usuario y viceversa). Varios tipos de eventos de Usuario no son necesariamente permanentes y pueden alternar entre estados indefinidamente. Estos incluyen: user_delete, user_undelete, user_protect, user_unprotect y user_suspend, user_unsuspend.

Los user_deletes van seguidos de status_deletes 30 días después solo si el usuario no ha elegido hacer user_undelete de su cuenta. Es posible que un user_delete sea revertido por el usuario y que las eliminaciones de todas sus Publicaciones 30 días más tarde no se produzcan.

user_suspend es una acción que se mantiene vigente a menos que el usuario esté sujeto a un evento user_unsuspend. Estos no están sujetos a ningún cambio asociado a un período de 30 días.

Nunca es adecuado mostrar directamente eventos de cumplimiento a los usuarios de tu software ni incorporarlos de otro modo en tus productos o experiencias de cliente. Están pensados únicamente para mantener el cumplimiento y respetar las acciones de los usuarios de X.

​

Integración con el Compliance Firehose

Para integrar el Compliance Firehose en tu sistema, deberás crear una integración que pueda hacer lo siguiente:

1. Establecer una conexión de streaming con cada partición de la API de streaming de Compliance Firehose
2. Manejar volúmenes de datos elevados: desacoplar la ingesta del stream del procesamiento adicional usando procesos asíncronos
3. Reconectarse automáticamente a las particiones del stream cuando se desconecten por cualquier motivo
4. Procesar los eventos de cumplimiento que sean relevantes para los datos de Publicación y Usuario que hayas almacenado, según las directrices presentadas anteriormente

​

Respetar la intención del usuario en X

Creemos que respetar la privacidad y la intención de los usuarios de X es fundamental para la salud a largo plazo de una de las mayores plataformas públicas de información en tiempo real del mundo. X pone los controles de privacidad en manos de sus usuarios, ofreciendo a cada persona la capacidad de controlar su propia experiencia en X. Como clientes empresariales que consumen datos de X, tenemos la responsabilidad colectiva de respetar la privacidad y las acciones de los usuarios finales para mantener este entorno de confianza y respeto.

Pueden ocurrir diversas cosas con las Publicaciones y las cuentas de Usuario que afectan cómo se muestran en la plataforma. Las acciones que afectan a la privacidad y a la intención se definen tanto a nivel de Estado (Publicación) como de Usuario. Estas acciones incluyen:

​

Usuario

Acción	Descripción
Proteger cuenta	Un usuario de X puede proteger o desproteger su cuenta en cualquier momento. Las cuentas protegidas requieren la aprobación manual, por parte del usuario, de cada persona a la que se le permite ver las Publicaciones de su cuenta.  Para obtener más información, consulta Acerca de las Publicaciones públicas y protegidas.
Eliminar cuenta	Un usuario de X puede decidir eliminar su cuenta y todas las Publicaciones asociadas en cualquier momento. X conserva la información de la cuenta durante 30 días después de la eliminación, en caso de que el usuario decida recuperarla y, en efecto, reactivar su cuenta.
Eliminar datos de ubicación	Un usuario de X puede quitar todos los datos de ubicación de Publicaciones anteriores en cualquier momento. Esto se conoce como “scrub geo”.
Suspender cuenta	X se reserva el derecho de suspender las cuentas que infrinjan las Reglas de X o si se sospecha que una cuenta ha sido hackeada o comprometida. Las suspensiones de cuenta solo pueden revertirse (levantar la suspensión) por X.
Restringir cuenta	X se reserva el derecho de restringir de forma reactiva el acceso a cierto contenido en un país específico de vez en cuando. Solo X puede revertir el estado de una cuenta restringida.  Para obtener más información, consulta Contenido restringido por país.

​

Estado

Acción	Descripción
Eliminar estado	Un usuario de X puede eliminar un estado en cualquier momento. Los estados eliminados no se pueden revertir y se eliminan de forma permanente.
Retener estado	X se reserva el derecho de retener de forma reactiva el acceso a cierto contenido en un país específico de vez en cuando. Solo X puede levantar la retención de un estado retenido.  Para obtener más información, consulta Contenido retenido por país.

​

Seguimiento de cambios en User y Status

El estado de un User o un Status puede cambiar en cualquier momento como resultado de cualquiera de las acciones anteriores, y esto afecta a la forma en que se espera que los consumidores de datos de X gestionen la disponibilidad y la privacidad de todo el contenido asociado. Cuando se producen estas acciones, se envía un mensaje de cumplimiento correspondiente que indica que el estado de un Status o un User ha cambiado.

​

Referencia de la API

​

GET compliance/firehose

​

Métodos

Método	Descripción
GET /compliance/:stream	Conectar con el flujo de datos

​

Autenticación

Todas las solicitudes a la API de Compliance Firehose deben usar Autenticación básica HTTP, construida a partir de una combinación válida de dirección de correo electrónico y contraseña que utilizas para iniciar sesión en tu cuenta en console.gnip.com. Las credenciales deben incluirse en el encabezado Authorization de cada solicitud.

​

GET /compliance/:stream

Establece una conexión persistente con el flujo de datos de Compliance firehose, a través del cual se entregarán los eventos de cumplimiento.

Request Method	HTTP GET
Connection Type	Keep-Alive
URL	Se encuentra en la página de ayuda de la API del stream en tu panel de control y tiene una estructura similar a la siguiente: https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1 Nota: El parámetro “partition” es obligatorio. Deberás conectarte a las 8 particiciones, cada una de las cuales contiene el 12,5% del volumen total, para consumir el flujo completo.
Compression	Gzip. Para conectarte al stream usando compresión Gzip, simplemente envía un encabezado Accept-Encoding en la solicitud de conexión. El encabezado debe tener el siguiente aspecto: Accept-Encoding: gzip
Character Encoding	UTF-8
Response Format	JSON. El encabezado de tu solicitud debe especificar el formato JSON para la respuesta.
Rate Limit	10 solicitudes cada 60 segundos.
Read Timeout	Configura un tiempo de espera de lectura en tu cliente y asegúrate de que esté establecido en un valor superior a 30 segundos.
Support for Tweet edits	Todas las ediciones de Tweets activan un evento de Compliance “tweet_edit”. Consulta la documentación de Compliance Data Objects para obtener más detalles.

Example Curl Request

La siguiente solicitud de ejemplo se realiza utilizando cURL en la línea de comandos:

curl --compressed -v [e-mail] "https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1"

Nota: la solicitud anterior solo se conecta a partition=1 del Compliance firehose; deberás conectarte a las 8 particiones para consumir la totalidad de este flujo.

​

Códigos de respuesta

La API puede devolver las siguientes respuestas para estas solicitudes. La mayoría de los códigos de error se devuelven con una cadena de texto con detalles adicionales en el cuerpo. Para respuestas distintas de 200, los clientes deben intentar reconectarse.

Status	Text	Definition
200	Success	La conexión se abrió correctamente y se enviarán nuevas actividades a medida que vayan llegando.
401	Unauthorized	La autenticación HTTP falló debido a credenciales inválidas. Inicia sesión en console.gnip.com con tus credenciales para asegurarte de que las usas correctamente en tu solicitud.
406	Not Acceptable	Generalmente, esto ocurre cuando tu cliente no incluye correctamente los encabezados para aceptar la codificación gzip desde el flujo, pero también puede ocurrir en otras circunstancias. Contendrá un mensaje JSON similar a: “This connection requires compression. To enable compression, send an ‘Accept-Encoding: gzip’ header in your request and be ready to uncompress the stream as it is read on the client end.”
429	Rate Limited	Tu App ha superado el límite de solicitudes de conexión.
503	Service Unavailable	Problema del servidor de Twitter. Vuelve a conectarte usando un patrón de backoff exponencial. Si no se ha publicado ningún aviso sobre este problema en la X API Status Page, ponte en contacto con el soporte.

​

Otras recomendaciones y buenas prácticas

• Diseña esquemas de almacenamiento de datos que almacenen el Tweet ID y el User ID numéricos: Los mensajes de usuario requieren que se tomen medidas sobre todos los Tweets de ese usuario. Por lo tanto, dado que todos los mensajes de cumplimiento se entregan únicamente por ID numérico, es importante diseñar esquemas de almacenamiento que mantengan la relación entre el Tweet y el usuario basándose en IDs numéricos. Los consumidores de datos deberán supervisar los eventos de cumplimiento tanto por Tweet ID como por User ID y poder actualizar el almacén de datos local de forma adecuada.

• Diseña esquemas que aborden todos los estados de cumplimiento: Dependiendo de cómo se gestionen las actividades de cumplimiento en varias aplicaciones, puede ser necesario agregar otros metadatos al almacén de datos. Por ejemplo, los consumidores de datos pueden decidir agregar metadatos a una base de datos existente para facilitar la restricción de la visualización de contenido en los países afectados por un mensaje status_withheld.

• Gestión de eliminaciones de Retweet: Los Retweets son un tipo especial de Tweet en el que el mensaje original está anidado en un objeto dentro del Retweet. En este caso, hay dos Tweet IDs referenciados en un Retweet: el ID del Retweet y el ID del mensaje original (incluido en el objeto anidado). Cuando se elimina un mensaje original, se emite un mensaje de eliminación de Tweet para el ID original. NO se emiten mensajes de eliminación posteriores para todos los Retweets. La eliminación del ID original debería ser suficiente para eliminar todos los Retweets posteriores.