> ## Documentation Index
> Fetch the complete documentation index at: https://generaltranslation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# v1에서 v2로 마이그레이션
export const Button = ({href, children}) => {
return ;
};
### 표준 v1.1과 X API v2 비교
표준 v1.1 `GET users/show` 및 `GET users/lookup` 엔드포인트를 사용해 오셨다면, 이 가이드의 목적은 표준과 X API v2의 사용자 조회(users lookup) 엔드포인트 간 유사점과 차이점을 이해하는 데 도움을 드리는 것입니다.
* **유사점**
* OAuth 1.0a 사용자 컨텍스트
* 요청당 사용자 수 제한
* **차이점**
* 엔드포인트 URL
* App 및 Project 요구 사항
* 응답 데이터 형식
* 요청 파라미터
#### 유사점
**OAuth 1.0a 사용자 컨텍스트 인증 방식**
표준 엔드포인트는 [OAuth 1.0a User Context](/ko/resources/fundamentals/authentication#oauth-1-0a-2)를 지원하며, 새로운 X API v2 users 조회 엔드포인트는 OAuth 1.0a User Context와 [App only](/ko/resources/fundamentals/authentication#oauth-2-0)를 모두 지원합니다. 따라서 이전에 표준 v1.1 users 조회 엔드포인트 중 하나를 사용하고 있었다면, X API v2 버전으로 마이그레이션하더라도 동일한 인증 방식을 그대로 사용할 수 있습니다.
사용 중인 인증 라이브러리/패키지에 따라 다를 수 있지만, App only 인증이 가장 시작하기 쉬운 방식인 경우가 많으며, 간단한 요청 헤더 설정만으로 구성할 수 있습니다. App only Access Token을 생성하는 방법은 [이 App only 가이드](/ko/resources/fundamentals/authentication#bearer-token-also-known-as-app-only)를 참고하세요.
**요청당 사용자 수 제한**
표준 v1.1 `GET users/lookup` 엔드포인트에서는 요청당 최대 100명의 사용자를 지정할 수 있습니다. 이는 `GET /users` 및 `GET /users/by` 엔드포인트에도 동일하게 적용됩니다. 전체 100명의 사용자를 지정하려면, `GET /users`의 경우 `ids` 파라미터를, `GET /users/by`의 경우 `username` 파라미터를 쿼리 파라미터로 전달하고, 사용자 ID/username 목록을 쉼표로 구분된 목록으로 포함해야 합니다.
#### 차이점
**엔드포인트 URL**
* 표준 v1.1 엔드포인트:
* [https://api.x.com/1.1/users/show](https://api.x.com/1.1/users/show) (단일 ID 또는 사용자 이름 조회)
* [https://api.x.com/1.1/users/lookup](https://api.x.com/1.1/users/lookup) (다중 ID 또는 사용자 이름 조회)
* X API v2 엔드포인트:
* [https://api.x.com/2/users](https://api.x.com/2/users) (다중 ID 조회)
* [https://api.x.com/2/users/:id](https://api.x.com/2/users/:id) (단일 ID 조회)
* [https://api.x.com/2/users/by](https://api.x.com/2/users/by) (다중 사용자 이름 조회)
* [https://api.x.com/2/users/by/username/:username](https://api.x.com/2/users/by/username/:username) (단일 사용자 이름 조회)
**App 및 Project 요구 사항**
X API v2 엔드포인트를 사용하려면, 요청을 인증할 때 [developer App](/ko/resources/fundamentals/developer-apps)의 자격 증명이 [Project](/ko/resources/fundamentals/developer-apps)와 연결되어 있어야 합니다. 모든 X API v1.1 엔드포인트는 단독 App 또는 Project와 연결된 App의 자격 증명을 사용할 수 있습니다.
**응답 데이터 형식**
표준 v1.1과 X API v2 엔드포인트 버전 간 가장 큰 차이점 중 하나는 페이로드에 어떤 필드를 반환할지 선택하는 방식입니다.
표준 엔드포인트의 경우, 많은 응답 필드를 기본적으로 받게 되며, 이후 매개변수를 사용해 어떤 필드 또는 필드 집합을 페이로드에 반환할지 지정할 수 있습니다.
X API v2 엔드포인트는 기본적으로 user id, name, username 필드만 제공합니다. 추가 필드나 객체를 요청하려면 [fields](/ko/x-api/fundamentals/fields) 및 [expansions](/ko/x-api/fundamentals/expansions) 매개변수를 사용해야 합니다. 이 엔드포인트에서 요청한 모든 user 필드는 기본 user 객체에 포함되어 반환됩니다. 확장된 게시물 객체와 필드는 응답 내 includes 객체에 포함되어 반환됩니다. 그런 다음 user 객체와 확장된 게시물 객체 양쪽에 있는 ID를 매칭하여, 확장된 객체를 다시 user 객체와 연결할 수 있습니다.
이 새로운 매개변수에 대해서는 각 가이드를 참고하시거나, [fields 및 expansions 사용 방법](/ko/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions)에 대한 가이드를 읽어 보시기를 권장합니다.
또한 표준 v1.1 필드를 새로운 v2 필드에 매핑하는 데 도움이 되는 [데이터 형식 마이그레이션 가이드](/ko/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2)를 제공합니다. 이 가이드에서는 v2 요청에서 특정 필드를 반환하기 위해 전달해야 하는 expansions 및 field 매개변수를 구체적으로 안내합니다.
특정 필드를 요청하는 방식의 변경 외에도, X API v2는 [Post](/ko/x-api/fundamentals/data-dictionary#tweet) 및 [user](/ko/x-api/fundamentals/data-dictionary#user) 객체를 포함하여 API가 반환하는 객체에 대해 새로운 JSON 설계를 도입합니다.
* JSON 루트 레벨에서, 표준 엔드포인트는 게시물 객체를 statuses 배열로 반환하는 반면, X API v2는 data 배열로 반환합니다.
* 리트윗 및 인용된 "statuses"를 참조하는 대신, X API v2 JSON은 리트윗 및 인용된 Tweet을 참조합니다. contributors, user.translator\_type과 같은 많은 레거시 및 사용 중단 필드는 제거됩니다.
* 게시물 객체에서 favorites, user 객체에서 favourites를 모두 사용하는 대신, X API v2는 like라는 용어를 사용합니다.
* X는 값이 없는 JSON 값(예: null)은 페이로드에 기록하지 않는 규칙을 채택하고 있습니다. 게시물 및 user 속성은 null이 아닌 값을 가진 경우에만 포함됩니다.
또한 [Post 객체](/ko/x-api/fundamentals/data-dictionary#tweet)에 다음과 같은 새로운 필드 집합을 도입했습니다.
* [conversation\_id](/ko/x-api/fundamentals/conversation-id) 필드
* context 및 entities를 포함하는 두 개의 새로운 [annotations](/ko/x-api/fundamentals/post-annotations) 필드
* 여러 개의 새로운 [metrics](/ko/x-api/fundamentals/metrics) 필드
* 특정 게시물에 누가 답글을 달 수 있는지를 보여주는 새로운 reply\_setting 필드
**요청 매개변수**
다음 표준 v1.1 요청 매개변수는 X API v2에서 다음과 같은 매개변수에 해당합니다.
| | |
| :----------- | :----------- |
| **표준** | **X API v2** |
| user\_id | ids |
| screen\_name | username |
또한 X API v2에서 지원되지 **않는** 표준 users 조회 요청 매개변수 집합도 있습니다.
| 표준 | 설명 |
| :---------------- | :----------------------------------------------------------------------------------------- |
| include\_entities | 이 매개변수는 게시물 페이로드에서 entities 노드를 제거하는 데 사용됩니다. 이 기능은 추가적인 fields 및 expansions 기능으로 대체되었습니다. |
***
### 코드 예제
다음 예제는 표준 v1.1 엔드포인트와 이에 대응하는 v2 엔드포인트를 보여줍니다.
**단일 사용자 조회: v1.1 `GET users/show` → v2 `GET /users/by/username/:username`**
```bash cURL (v1.1) theme={null}
curl --request GET \
--url 'https://api.x.com/1.1/users/show.json?screen_name=XDevelopers' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
```
```bash cURL (v2) theme={null}
curl --request GET \
--url 'https://api.x.com/2/users/by/username/XDevelopers?user.fields=created_at,description,public_metrics' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
```
```python Python (v2) theme={null}
import requests
bearer_token = "YOUR_BEARER_TOKEN"
url = "https://api.x.com/2/users/by/username/XDevelopers"
params = {
"user.fields": "created_at,description,public_metrics"
}
headers = {"Authorization": f"Bearer {bearer_token}"}
response = requests.get(url, headers=headers, params=params)
print(response.json())
```
```python Python SDK theme={null}
from xdk import Client
client = Client(bearer_token="YOUR_BEARER_TOKEN")
# 추가 필드를 포함해 username으로 사용자 조회
response = client.users.get_by_username(
"XDevelopers",
user_fields=["created_at", "description", "public_metrics"]
)
print(f"Name: {response.data.name}")
print(f"Followers: {response.data.public_metrics.followers_count}")
```
```javascript JavaScript SDK theme={null}
import { Client } from "@xdevplatform/xdk";
const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });
const response = await client.users.getByUsername("XDevelopers", {
userFields: ["created_at", "description", "public_metrics"],
});
console.log(`Name: ${response.data?.name}`);
console.log(`Followers: ${response.data?.public_metrics?.followers_count}`);
```
**여러 사용자 조회: v1.1 `GET users/lookup` → v2 `GET /users/by`**
```bash cURL (v1.1) theme={null}
curl --request GET \
--url 'https://api.x.com/1.1/users/lookup.json?screen_name=XDevelopers,X,XAPI' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
```
```bash cURL (v2) theme={null}
curl --request GET \
--url 'https://api.x.com/2/users/by?usernames=XDevelopers,X,XAPI&user.fields=created_at,public_metrics' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
```
```python Python (v2) theme={null}
import requests
bearer_token = "YOUR_BEARER_TOKEN"
url = "https://api.x.com/2/users/by"
params = {
"usernames": "XDevelopers,X,XAPI",
"user.fields": "created_at,public_metrics"
}
headers = {"Authorization": f"Bearer {bearer_token}"}
response = requests.get(url, headers=headers, params=params)
for user in response.json()["data"]:
print(f"{user['username']}: {user['public_metrics']['followers_count']} followers")
```
```python Python SDK theme={null}
from xdk import Client
client = Client(bearer_token="YOUR_BEARER_TOKEN")
# 여러 사용자를 username으로 조회
response = client.users.get_users_by_usernames(
usernames=["XDevelopers", "X", "XAPI"],
user_fields=["created_at", "public_metrics"]
)
for user in response.data:
print(f"{user.username}: {user.public_metrics.followers_count} followers")
```
```javascript JavaScript SDK theme={null}
import { Client } from "@xdevplatform/xdk";
const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });
const response = await client.users.getUsersByUsernames({
usernames: ["XDevelopers", "X", "XAPI"],
userFields: ["created_at", "public_metrics"],
});
response.data?.forEach((user) => {
console.log(`${user.username}: ${user.public_metrics?.followers_count} followers`);
});
```