메인 콘텐츠로 건너뛰기
참고 X API v2에 배치 컴플라이언스라는 새로운 컴플라이언스 도구를 출시했습니다. 이 도구를 사용하면 대규모 게시물 또는 사용자 ID 데이터세트를 업로드해 컴플라이언스 상태를 조회하고, 데이터세트를 규정 준수 상태로 맞추기 위해 어떤 데이터에 조치가 필요한지 판단할 수 있습니다.
또한 배치 컴플라이언스와 컴플라이언스 파이프라인 모두 게시물 편집을 지원하도록 업데이트되었습니다. 컴플라이언스 파이프라인에는 새로운 ‘tweet_edit’ 이벤트가 추가되었습니다. 자세한 내용은 Compliance Data Objects 문서를 참조하세요. 게시물 편집 메타데이터의 동작 방식은 Edit Posts 기본 사항 페이지에서 확인하세요.

개요

Enterprise X의 핵심 가치 중 하나는 사용자의 목소리를 보호하고 존중하는 것입니다. 여기에는 사용자가 X에서 공유하기로 선택한 콘텐츠를 삭제, 수정 또는 편집할 때 그들의 기대와 의도를 존중하는 것이 포함됩니다. 우리는 이것이 세계 최대 규모의 공개 실시간 정보 플랫폼 중 하나의 장기적 건전성에 매우 중요하다고 믿습니다. X는 사용자에게 통제권을 부여하여 개인이 자신의 X 경험을 직접 관리할 수 있도록 합니다. 우리는 X 데이터를 수신하는 비즈니스 고객이 최종 사용자의 기대와 의도를 존중할 책임이 있다고 믿습니다. X 플랫폼에서 가능한 준수 이벤트 유형에 대한 자세한 내용은 문서 Honoring User Intent on X를 참조하세요. API를 통해 X 데이터를 활용하는 모든 개발자와 회사는 사용자 콘텐츠 변경 사항을 존중하기 위해 합리적으로 가능한 모든 노력을 기울일 의무가 있습니다. 이 의무는 삭제, 수정, 공유 옵션 변경(예: 콘텐츠가 보호되거나 보류됨)과 같은 사용자 이벤트뿐 아니라 사용자가 자신의 게시물을 편집하는 경우에도 적용됩니다. 이 의무가 X 데이터 사용에 어떤 영향을 미치는지 이해하려면 Developer Policy 및/또는 X Data Agreement의 관련 조항을 참고하세요. X는 이러한 사용자 준수 이벤트에 대한 정보와 특정 게시물 또는 사용자가 공개적으로 이용 가능한지 여부를 제공하는 다음 솔루션을 제공합니다. 각 솔루션과 일반적인 통합 패턴의 간략한 개요는 아래에 설명되어 있습니다:

GET statuses/lookup 및 GET users/lookup

  • 형식: REST API 참조: GET statuses/lookupGET users/lookup.
  • 이 엔드포인트는 항상 게시물 편집의 최신 버전을 반환합니다. 편집 기능 도입 이후 생성된 게시물을 설명하는 모든 게시물 객체에는 게시물 편집 메타데이터가 포함됩니다. 이는 편집되지 않은 게시물에도 적용됩니다.
  • 모든 게시물에 대해, 생성 후 30분이 지난 시점의 요청은 해당 게시물의 최종 상태를 반환합니다.
  • API 요청에서 호출자가 지정한 특정 게시물 또는 사용자의 가용성 정보를 제공합니다.
  • 특정 게시물/사용자 그룹의 현재 가용 상태를 임시 점검(ad-hoc spot-checking)하는 데 사용할 수 있습니다.
  • 특정 시점에 특정 게시물 또는 사용자의 현재 상태를 확인해야 하는 고객에게 적합합니다.
  • 이러한 API는 콘텐츠의 가용성을 확인해야 하는 고객에게 유용한 메커니즘을 제공합니다. 예를 들어 다음과 같은 경우:
    1. 게시물 표시
    2. 1:1 방식으로 게시물 또는 사용자와 상호작용
    3. 허용된 파일 다운로드를 통해 타사에 X 콘텐츠 배포
    4. 장기간 게시물 저장

Compliance Firehose (엔터프라이즈 전용)

  • 형식: 스트리밍 API 참고: Compliance Firehose.
  • X에서 발생하는 컴플라이언스 활동의 실시간 스트림을 제공합니다. 여기에는 게시물 편집과 같은 활동이 포함됩니다.
  • 플랫폼에서 새로운 컴플라이언스 이벤트가 발생할 때 저장된 데이터 집합 전반의 컴플라이언스 상태를 유지하는 데 사용할 수 있습니다.
  • 장기간 대량의 X 데이터를 수집하고 저장하는 고객에게 적합합니다.

안내서

컴플라이언스 모범 사례

권장 사항 및 모범 사례

  • 숫자형 Post ID 및 User ID를 저장하는 데이터 스키마 구축: 사용자 메시지에 대해서는 해당 사용자의 모든 게시물에 조치가 필요합니다. 모든 컴플라이언스 메시지는 숫자형 ID로만 전달되므로, 숫자형 ID를 기반으로 게시물과 사용자 간의 관계를 유지하도록 저장 스키마를 설계하는 것이 중요합니다. 데이터 소비자는 Post ID와 User ID 모두를 기준으로 컴플라이언스 이벤트를 모니터링하고, 로컬 데이터 저장소를 적절히 업데이트할 수 있어야 합니다.
  • 모든 컴플라이언스 상태를 처리하는 스키마 구축: 애플리케이션에서 컴플라이언스 작업을 어떻게 처리하느냐에 따라 데이터 저장소에 다른 메타데이터를 추가해야 할 수 있습니다. 예를 들어, 데이터 소비자는 status_withheld 메시지의 영향을 받는 국가에서 콘텐츠 표시를 제한하기 쉽도록 기존 데이터베이스에 메타데이터를 추가할 수 있습니다.
  • 리포스트 삭제 처리: 리포스트는 원본 메시지가 리포스트 내부의 객체에 중첩되어 있는 특수한 유형의 게시물입니다. 이 경우 리포스트에는 두 개의 Post ID가 참조됩니다. 리포스트의 ID와 원본 메시지의 ID(중첩 객체에 포함됨)입니다. 원본 메시지가 삭제되면 원본 ID에 대해 게시물 삭제 메시지가 발행됩니다. 게시물 삭제 이벤트는 보통 모든 리포스트에 대한 삭제 이벤트를 트리거합니다. 그러나 경우에 따라 모두 전송되지 않을 수 있으므로 클라이언트 시스템은 불완전한 리포스트 삭제를 허용해야 합니다. 원본 ID가 삭제되면 이후의 모든 리포스트를 삭제하는 데 충분합니다. 리포스트를 저장할 때는 원본 Post ID를 참조하고, 게시물 삭제 이벤트를 수신하면 참조된 모든 리포스트를 삭제하는 것이 모범 사례입니다.

규정 준수 데이터 객체

Compliance Firehose API

가능한 컴플라이언스 이벤트 유형에는 게시물(또는 “status”) 이벤트와 사용자 이벤트가 포함되며, 각 유형은 아래에 자세히 설명되어 있습니다.   유의하세요:
  • 사용자 상태에 대한 자세한 내용은 여기에서, 삭제된 게시물에 대한 개발자 정책은 여기에서 확인하세요.
  • Compliance Firehose가 ‘tweet_edit’ 이벤트를 제공하도록 업데이트되었습니다. 
  • 여러 사용자 삭제, 보호, 정지 이벤트는 반드시 영구적인 것이 아니며 상태 간에 무한히 전환될 수 있습니다. 여기에는 다음이 포함됩니다: user_delete, user_undelete, user_protect, user_unprotect, user_suspend, user_unsuspend.
  • user_delete가 발생한 후 사용자가 계정을 user_undelete하지 않은 경우에 한해 30일 뒤 status_delete가 뒤따릅니다. 사용자가 user_delete를 번복하면 30일 후 해당 사용자의 모든 게시물에 대한 삭제가 발생하지 않을 수 있습니다.
  • user_suspend는 사용자가 user_unsuspend 이벤트의 대상이 되지 않는 한 계속 유효한 조치입니다. 이는 30일 기간과는 무관하게 변경되지 않습니다.
최종 사용자의 프라이버시와 의도를 존중하기 위해 각 이벤트 유형을 처리하는 방법은 ‘권장 조치’ 열을 참고하세요.
원본 메시지 유형객체영구 여부 (예/아니오)권장 조치
deleteStatusYes관련 게시물을 삭제합니다.
status_withheldStatusYesstatus_withheld 메시지에 나열된 특정 국가에서 해당 게시물을 숨깁니다.
dropStatusNo게시물을 공개 보기에서 제거합니다.
undropStatusNo해당 상태를 다시 표시하고 공개로 취급합니다.
tweet_editStatusYes편집 내용을 반영하고, 필요 시 이를 표시합니다.
user_deleteUserNo해당 사용자의 모든 게시물을 숨기거나 삭제합니다.
user_undeleteUserNo해당 사용자의 모든 게시물을 다시 표시하고 공개로 취급합니다.
user_protectUserNo해당 사용자의 모든 게시물을 숨기거나 삭제합니다.
user_unprotectUserNo해당 사용자의 모든 게시물을 다시 표시하고 공개로 취급합니다.
user_suspendUserNo해당 사용자의 모든 게시물을 숨기거나 삭제합니다.
user_unsuspendUserNo해당 사용자의 모든 게시물을 다시 표시하고 공개로 취급합니다.
scrub_geoUserYesscrub_geo 메시지에 지정된 게시물 이전에 해당 사용자가 작성한 모든 게시물에서 X가 제공한 모든 지오데이터를 삭제합니다. 이후 게시물에는 사용할 수 있는 지오데이터가 포함될 수 있습니다.
user_withheldUserYesuser_withheld 메시지에 나열된 특정 국가에서 해당 사용자의 게시물을 숨깁니다.
deleteFavoriteYes관련 좋아요/즐겨찾기를 삭제합니다.

페이로드 예시

위 표에 설명된 각 컴플라이언스 이벤트의 페이로드 예시는 아래를 참고하세요. 게시물 편집
{"tweet_edit":
   {
     "id": "1557445923210514432"
     "initial_tweet_id": "1557433858676740098",
     "edit_tweet_ids": ["1557433858676740098", "1557445923210514432"],
     "timestamp_ms": "1660155761384"
   }
 }
게시물 삭제
{
  "delete": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220608",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}
게시물 보류 처리됨
{
  "status_withheld": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220608",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "withheld_in_countries": [
      "XY"
    ],
    "timestamp_ms": "1432228155593"
  }
}
드롭
{
  "drop": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220600",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}
복구 취소
{
  "undrop": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220600",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}

위치 정보 정리

{
  "scrub_geo": {
    "user_id": 519761961,
    "up_to_status_id": 411552403083628540,
    "up_to_status_id_str": "411552403083628544",
    "user_id_str": "519761961",
    "timestamp_ms": "1432228180345"
  }
}
사용자 삭제
{
  "user_delete": {
    "id": 771136850,
    "timestamp_ms": "1432228153548"
  }
}
사용자 복구
{
  "user_undelete": {
    "id": 796250066,
    "timestamp_ms": "1432228149062"
  }
}
사용자 보류됨
{
  "user_withheld": {
    "user": {
      "id": 1375036644,
      "id_str": "1375036644"
    },
    "withheld_in_countries": [
      "XY"
    ],
    "timestampMs": "2014-08-27T23:49:41.839+00:00"
  }
}
사용자 보호 설정
{
  "user_protect": {
    "id": 3182003550,
    "timestamp_ms": "1432228177137"
  }
}
사용자 보호 해제
{
  "user_unprotect": {
    "id": 2911076065,
    "timestamp_ms": "1432228180113"
  }
}
사용자 정지
{
  "user_suspend": {
    "id": 3120539094,
    "timestamp_ms": "1432228194217"
  }
}
사용자 정지 해제
{
  "user_unsuspend": {
    "id": 3293130873,
    "timestamp_ms": "1432228193828"
  }
}

Compliance Firehose 통합

Compliance Firehose는 X 플랫폼에서 발생하는 컴플라이언스 이벤트를 실시간으로 제공하는 스트리밍 API입니다. X에서 컴플라이언스 이벤트가 무엇이며 어떻게 생성되는지 이해하려면 다음 문서를 참고하세요: Honoring User Intent on X. 게시물과 사용자 이벤트는 서로 독립적으로 전달되며 각각 별도로 처리해야 합니다(예: 게시물 삭제가 사용자 이벤트를 의미하지 않으며, 그 반대도 마찬가지입니다). 여러 사용자 이벤트는 영구적이지 않을 수 있으며 상태 간을 무한히 전환될 수 있습니다. 여기에는 다음이 포함됩니다: user_delete, user_undelete, user_protect, user_unprotect, user_suspend, user_unsuspend. user_delete 이후 30일 뒤에는, 사용자가 계정에 대해 user_undelete를 선택하지 않은 경우에 한해 status_delete가 발생합니다. 사용자가 user_delete를 취소해 30일 후 해당 사용자의 모든 게시물 삭제가 발생하지 않을 수도 있습니다. user_suspend는 사용자가 user_unsuspend 이벤트의 대상이 되지 않는 한 계속 유효한 조치입니다. 이는 30일 기간과 관련한 어떤 변경의 대상도 아닙니다. 컴플라이언스 이벤트를 소프트웨어 사용자에게 직접 표시하거나, 제품 또는 고객 경험에 이를 포함하는 것은 결코 적절하지 않습니다. 이러한 이벤트는 오직 컴플라이언스를 유지하고 X 사용자의 의도를 존중하기 위한 목적으로만 제공됩니다.

Compliance Firehose 통합

Compliance Firehose를 시스템에 통합하려면 다음 기능을 갖춘 통합을 구축해야 합니다:
  1. Compliance Firehose의 각 스트리밍 API 파티션에 스트리밍 연결을 설정합니다
  2. 비동기 프로세스를 사용해 스트림 수집을 후속 처리와 분리하여 대용량 데이터를 처리합니다
  3. 어떤 이유로든 연결이 끊어지면 스트림 파티션에 자동으로 재연결합니다
  4. 위에 제시된 지침에 따라 저장한 게시물 및 사용자 데이터와 관련된 컴플라이언스 이벤트를 처리합니다

Twitter에서 사용자 의도 존중하기

우리는 X 사용자의 프라이버시와 의도를 존중하는 것이 세계 최대 규모의 공개 실시간 정보 플랫폼 중 하나의 장기적 건전성에 매우 중요하다고 믿습니다. X는 프라이버시 제어권을 사용자에게 제공하여 개인이 자신의 X 경험을 직접 관리할 수 있도록 합니다. X 데이터의 비즈니스 이용자로서 우리는 신뢰와 존중의 환경을 유지하기 위해 최종 사용자의 프라이버시와 행동을 존중해야 할 공동의 책무가 있습니다. 플랫폼에서의 표시 방식에 영향을 줄 수 있는 일은 게시물과 사용자 계정에 다양하게 발생할 수 있습니다. 프라이버시와 의도에 영향을 미치는 조치는 게시물(상태) 수준과 사용자 수준 모두에서 정의됩니다. 이러한 조치에는 다음이 포함됩니다:

사용자

작업설명
계정 보호X 사용자는 언제든지 자신의 계정을 보호하거나 보호 해제할 수 있습니다. 보호된 계정의 게시물은 열람을 허용할 각 사용자를 계정 소유자가 수동으로 승인해야 합니다. 
자세한 내용은 공개 및 보호된 게시물을 참고하세요.
계정 삭제X 사용자는 언제든지 자신의 계정과 해당 계정에 연결된 모든 게시물을 삭제할 수 있습니다. 사용자가 삭제를 취소해 계정을 다시 활성화할 수 있도록, X는 삭제 후 30일 동안 계정 정보를 보관합니다.
위치 정보 정리X 사용자는 언제든지 과거 게시물에서 모든 위치 데이터를 제거할 수 있습니다. 이를 “scrub geo”라고 합니다.
계정 정지X는 X 규칙을 위반했거나 계정이 해킹 또는 침해된 것으로 의심되는 경우 계정을 정지할 권리를 보유합니다. 계정 정지는 X에서만 해제(정지 해제)할 수 있습니다.
계정 제한X는 특정 국가에서 특정 콘텐츠에 대한 접근을 수시로 제한(보류)할 권리를 보유합니다. 제한된 계정은 X에서만 제한을 해제할 수 있습니다. 
자세한 내용은 국가별 제한 콘텐츠을 참고하세요.

상태

작업설명
상태 삭제X 사용자는 언제든지 상태를 삭제할 수 있습니다. 삭제된 상태는 되돌릴 수 없으며 영구적으로 삭제됩니다.
상태 보류X는 필요에 따라 특정 국가에서 일부 콘텐츠에 대한 접근을 사후적으로 제한(보류)할 권리를 보유합니다. 보류된 상태는 X만 보류 해제할 수 있습니다. 
자세한 내용은 Country Withheld Content를 참조하세요.

사용자 및 상태 변경 사항 추적

위의 작업 중 하나로 인해 사용자(User) 또는 상태(Status)의 상태는 언제든지 변경될 수 있으며, 이는 X 데이터 소비자가 관련 콘텐츠의 가용성과 개인정보 보호를 어떻게 처리해야 하는지에 영향을 줍니다. 이러한 작업이 발생하면 상태(Status) 또는 사용자(User)의 상태 변경을 알리는 관련 컴플라이언스 메시지가 전송됩니다.

API 참고 문서

GET compliance/firehose

메서드

메서드설명
GET /compliance/:stream데이터 스트림에 연결합니다

인증

Compliance Firehose API에 대한 모든 요청은 HTTP Basic 인증을 사용해야 하며, console.gnip.com에 로그인할 때 사용하는 유효한 이메일 주소와 비밀번호 조합으로 구성됩니다. 각 요청마다 자격 증명은 Authorization 헤더로 전달해야 합니다.

GET /compliance/:stream

Compliance firehose 데이터 스트림에 대한 지속적 연결을 설정하여 이를 통해 컴플라이언스 이벤트가 전달됩니다.
Request MethodHTTP GET
Connection TypeKeep-Alive
URL대시보드의 스트림 API 도움말 페이지에서 확인할 수 있으며, 다음과 같은 구조와 유사합니다:


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

참고: “partition” 매개변수는 필수입니다. 전체 스트림을 수신하려면 총 8개의 파티션 모두에 연결해야 하며, 각 파티션은 전체 볼륨의 12.5%를 포함합니다.
CompressionGzip. Gzip 압축으로 스트림에 연결하려면 연결 요청에 Accept-Encoding 헤더만 추가하면 됩니다. 헤더는 다음과 같습니다:

Accept-Encoding: gzip
Character EncodingUTF-8
Response FormatJSON. 요청 헤더에 응답 형식으로 JSON을 지정해야 합니다.
Rate Limit60초당 10회 요청
Read Timeout클라이언트에서 읽기 타임아웃을 설정하고 30초를 초과하는 값으로 설정했는지 확인하세요.
Support for Tweet edits모든 Tweet 편집은 “tweet_edit” 컴플라이언스 이벤트를 트리거합니다. 자세한 내용은 Compliance Data Objects 문서를 참조하세요.
Example Curl Request 다음 예시 요청은 명령줄에서 cURL로 실행됩니다:
curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1"
참고: 위의 요청은 Compliance firehose의 partition=1에만 연결됩니다. 이 스트림 전체를 소비하려면 8개 모든 파티션에 연결해야 합니다.

응답 코드

이 요청에 대해 API가 다음과 같은 응답을 반환할 수 있습니다. 대부분의 오류 코드는 본문에 추가 세부 정보 문자열과 함께 반환됩니다. 200 이외의 응답인 경우 클라이언트는 재연결을 시도해야 합니다.
StatusTextDefinition
200Success연결이 성공적으로 열렸으며, 새 활동이 도착하는 대로 전송됩니다.
401Unauthorized유효하지 않은 자격 증명으로 인해 HTTP 인증에 실패했습니다. 요청에서 자격 증명을 올바르게 사용하고 있는지 확인하려면 console.gnip.com에 로그인하세요.
406Not Acceptable일반적으로 스트림에서 gzip 인코딩을 허용하는 헤더를 클라이언트가 제대로 포함하지 않았을 때 발생하지만, 다른 상황에서도 발생할 수 있습니다. “이 연결에는 압축이 필요합니다. 압축을 활성화하려면 요청에 ‘Accept-Encoding: gzip’ 헤더를 포함하고, 클라이언트 측에서 스트림을 읽을 때 압축 해제할 준비를 하세요.”와 유사한 JSON 메시지가 포함됩니다.
429Rate Limited앱이 연결 요청 한도를 초과했습니다.
503Service UnavailableX 서버 문제입니다. 지수 백오프 패턴을 사용해 재연결하세요. 이 문제에 대한 공지가 X API 상태 페이지에 게시되지 않았다면 지원팀에 문의하세요.

기타 권장 사항 및 모범 사례

  • 숫자형 Tweet ID와 User ID를 저장하는 데이터 저장 스키마 구축: 사용자 메시지는 해당 사용자의 모든 Tweet에 대한 조치를 요구합니다. 따라서 모든 컴플라이언스 메시지가 숫자 ID로만 전달되므로, 숫자 ID를 기준으로 Tweet과 User 간의 관계를 보존하는 저장 스키마를 설계하는 것이 중요합니다. 데이터 소비자는 Tweet ID와 User ID를 모두 기준으로 컴플라이언스 이벤트를 모니터링하고, 로컬 데이터 저장소를 적절히 업데이트할 수 있어야 합니다.
  • 모든 컴플라이언스 상태를 처리하는 스키마 구축: 애플리케이션별로 컴플라이언스 작업을 처리하는 방식에 따라 데이터 저장소에 추가 메타데이터를 포함해야 할 수 있습니다. 예를 들어, 데이터 소비자는 status_withheld 메시지의 영향을 받는 국가에서 콘텐츠 표시를 제한할 수 있도록 기존 데이터베이스에 메타데이터를 추가하기로 결정할 수 있습니다.
  • 리트윗 삭제 처리: 리트윗은 원본 메시지가 리트윗 내부 객체에 중첩된 특수한 유형의 Tweet입니다. 이 경우 리트윗에는 두 개의 Tweet ID가 참조됩니다 — 리트윗의 ID와 원본 메시지의 ID(중첩 객체에 포함). 원본 메시지가 삭제되면 원본 ID에 대해 Tweet 삭제 메시지가 발행됩니다. 이후 모든 리트윗에 대해 추가 삭제 메시지는 발행되지 않습니다. 원본 ID의 삭제만으로 이후의 모든 리트윗도 삭제된 것으로 처리됩니다.