v1에서 v2로 마이그레이션

Standard v1.1과 X API v2 비교

기존에 standard v1.1의 GET statuses/show 및 GET statuses/lookup을 사용해 왔다면, 이 가이드는 standard와 X API v2 포스트 조회 endpoint 간의 유사점과 차이점을 이해하는 데 도움이 됩니다. X API v1.1 데이터 형식과 X API v2 형식의 차이를 빠르게 확인할 수 있도록 도와주는 시각적 데이터 형식 마이그레이션 도구도 참고하실 수 있습니다.

유사점
- OAuth 1.0a 사용자 컨텍스트
- 요청당 포스트 수 제한
- 포스트 수정 이력 및 메타데이터 지원
차이점
- 엔드포인트 URL
- App 및 Project 요구 사항
- 응답 데이터 형식
- 요청 매개변수

공통점

OAuth 1.0a 사용자 컨텍스트 인증 방식

표준 엔드포인트는 OAuth 1.0a User Context를 지원하고, 새 X API v2 게시물 조회 엔드포인트는 OAuth 1.0a User Context와 OAuth 2.0 App-Only를 모두 지원합니다. 따라서 이전에 표준 v1.1 게시물 조회 엔드포인트 중 하나를 사용했다면, X API v2 버전으로 마이그레이션하더라도 동일한 인증 방식을 계속 사용할 수 있습니다. App-Only 인증은 가장 간단하게 시작할 수 있는 방법입니다. App Access Token을 생성하는 방법은 이 OAuth 2.0 App-Only 가이드를 참고하세요.

요청당 포스트 수 제한

v1.1 GET statuses/lookup 엔드포인트를 사용하면 요청당 최대 100개의 포스트를 지정할 수 있습니다. 이는 GET /tweets 엔드포인트에도 적용됩니다. 정확히 100개의 게시물을 지정하려면 ids 매개변수를 쿼리 매개변수로 사용하여 쉼표로 구분된 Post IDs 목록을 전달하세요. 게시물 수정 이력 및 메타데이터 지원 두 버전 모두 수정 이력을 설명하는 메타데이터를 제공합니다. 자세한 내용은 Post 조회 API 참조 문서와 Edit Posts 기본 사항 페이지를 확인하세요.

차이점

엔드포인트 URL들

Standard v1.1 엔드포인트:
- https://api.x.com/1.1/statuses/show
- https://api.x.com/1.1/statuses/lookup
X API v2 엔드포인트:
- https://api.x.com/2/tweets
- https://api.x.com/2/tweets/:id

App 및 Project 요구 사항

X API v2 엔드포인트는 인증을 위해 Project에 연결된 developer App의 자격 증명이 필요합니다. X API v1.1 엔드포인트는 Project에 연결되지 않은 App 또는 Project에 연결된 App의 자격 증명을 모두 사용할 수 있습니다.

응답 데이터 형식

표준 v1.1과 X API v2 엔드포인트 버전 간의 중요한 차이점 중 하나는 페이로드에서 필드를 선택하는 방식입니다. 표준 엔드포인트의 경우, 많은 응답 필드가 기본적으로 포함되며, 매개변수를 사용해 추가 필드를 지정할 수 있습니다. 반면 X API v2는 기본적으로 게시물 id 및 text 필드만 제공합니다. 추가 필드와 객체를 받으려면 fields 및 expansions 매개변수를 사용해야 합니다. 확장된 필드는 응답의 includes 객체에 포함되며, ID를 매칭해 기본 게시물 객체와 연결할 수 있습니다. fields 및 expansions 사용에 대한 자세한 내용은 fields 및 expansions 사용 방법 가이드를 참조하세요. 데이터 형식 마이그레이션 가이드는 표준 v1.1 필드를 새로운 v2 필드에 매핑해 제공합니다. 또한 X API v2는 게시물 및 user 객체를 포함한 객체에 대해 새로운 JSON 구조를 도입합니다:

표준 엔드포인트는 statuses 배열로 게시물 객체를 반환하지만, X API v2는 data 배열을 사용합니다.
X API v2에서는 리트윗된 Tweet 및 인용 Tweet이라는 용어가 기존 “statuses” 용어를 대체합니다.
favorites 및 favourites와 같은 용어 대신 like와 같은 새로운 용어를 사용합니다.
값이 없는 속성(예: null)은 X API v2 페이로드에 포함되지 않습니다.

X API v2의 게시물 객체에는 다음과 같은 새로운 필드가 포함됩니다:

conversation_id
두 개의 새로운 annotations 필드 (context 및 entities)
새로운 metrics 필드
특정 게시물에 누가 답글을 달 수 있는지를 나타내는 reply_setting 필드

요청 매개변수

다음 표는 표준 v1.1 요청 매개변수와 X API v2에서의 대응 항목을 보여줍니다:

표준	X API v2
`id`	`ids`

일부 표준 v1.1 매개변수는 X API v2에서 지원되지 않습니다:

표준	설명
`tweet_mode`	fields 및 expansions 기능으로 대체되었습니다.
`trim_user`	fields 및 expansions로 대체되었습니다. 사용자 데이터에는 `author_id` expansions와 `user.fields`를 사용하세요.
`include_my_retweet`	인증된 사용자가 리트윗한 포스트에 대해 원본 포스트의 ID를 제공합니다.
`include_entities`	페이로드 내 엔티티를 제어하기 위해 fields 및 expansions를 사용하세요.
`include_ext_alt_text`	alt 텍스트가 있을 경우 media 엔티티에 `ext_alt_text` 필드를 추가합니다.
`include_card_uri`	광고 카드가 첨부된 경우 `card_uri`를 추가합니다.
`map`	v1.1에서 필드가 null로 반환되던 것과 달리, X API v2에서는 사용 불가한 포스트에 대해 포스트 ID와 오류 메시지를 반환합니다.

코드 예시

다음 예시는 표준 v1.1 엔드포인트와 이에 대응하는 v2 엔드포인트를 보여 줍니다. 자격 증명 값은 실제 토큰으로 교체하세요. v2 엔드포인트의 경우, 토큰은 Project 내의 developer App에 속해야 합니다. v1.1의 응답 페이로드는 v2와 다릅니다. v2에서는 fields 및 expansions 파라미터로 다양한 필드를 요청할 수 있습니다. 여러 포스트 조회: v1.1 GET statuses/lookup → v2 GET /tweets

cURL (v1.1)

curl --request GET \
  --url 'https://api.x.com/1.1/statuses/lookup.json?id=1460323737035677698%2C1460323743339741184' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

curl --request GET \
  --url 'https://api.x.com/2/tweets?ids=1460323737035677698%2C1460323743339741184&tweet.fields=created_at&expansions=author_id&user.fields=created_at' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

import requests

bearer_token = "YOUR_BEARER_TOKEN"
url = "https://api.x.com/2/tweets"

params = {
    "ids": "1460323737035677698,1460323743339741184",
    "tweet.fields": "created_at",
    "expansions": "author_id",
    "user.fields": "created_at"
}

headers = {"Authorization": f"Bearer {bearer_token}"}
response = requests.get(url, headers=headers, params=params)

print(response.json())

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# ID 목록으로 여러 포스트를 조회하고 fields 및 expansions를 지정합니다.
response = client.posts.get_posts(
    ids=["1460323737035677698", "1460323743339741184"],
    tweet_fields=["created_at"],
    expansions=["author_id"],
    user_fields=["created_at"]
)

for post in response.data:
    print(f"Post: {post.text}")
    print(f"Created at: {post.created_at}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// ID 목록으로 여러 포스트를 조회하고 fields 및 expansions를 지정합니다.
const response = await client.posts.getPosts({
  ids: ["1460323737035677698", "1460323743339741184"],
  tweetFields: ["created_at"],
  expansions: ["author_id"],
  userFields: ["created_at"],
});

response.data?.forEach((post) => {
  console.log(`Post: ${post.text}`);
  console.log(`Created at: ${post.created_at}`);
});

단일 게시물 조회: v1.1 GET statuses/show/:id → v2 GET /tweets/:id