> ## 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.

# 마이그레이션 가이드

export const Button = ({href, children}) => {
  return <div className="not-prose group">
    <a href={href}>
      <button className="flex items-center space-x-2.5 py-1 px-4 bg-primary-dark dark:bg-white text-white dark:text-gray-950 rounded-full group-hover:opacity-[0.9] font-medium">
        <span>
          {children}
        </span>
        <svg width="3" height="24" viewBox="0 -9 3 24" class="h-6 rotate-0 overflow-visible"><path d="M0 0L3 3L0 6" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"></path></svg>
      </button>
    </a>
  </div>;
};

<div id="blocks-lookup-standard-v11-compared-to-x-api-v2">
  ### 차단 조회: 표준 v1.1과 X API v2 비교
</div>

표준 v1.1 [GET blocks/ids](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-blocks-ids) 및 [GET blocks/list](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-blocks-list) 엔드포인트를 사용해 왔다면, 이 가이드는 표준 v1.1과 X API v2 차단 조회 엔드포인트 간의 공통점과 차이점을 이해하는 데 도움을 주기 위한 것입니다.

* **유사점**
  * 인증
* **차이점**
  * 엔드포인트 URL

  * 요청당 사용자 수 제한

  * App 및 Project 요구 사항

  * 응답 데이터 형식

  * 요청 파라미터

<div id="similarities">
  #### 유사점
</div>

**인증**

standard v1.1 및 X API v2 blocks lookup 엔드포인트는 모두 [OAuth 1.0a User Context](/ko/resources/fundamentals/authentication#oauth-1-0a-2)를 사용합니다. 따라서 이전에 standard v1.1 blocks lookup 엔드포인트 중 하나를 사용해 왔다면, X API v2 버전으로 마이그레이션하더라도 동일한 인증 방식을 그대로 사용할 수 있습니다. 

<div id="differences">
  #### 차이점
</div>

**엔드포인트 URL**

* Standard v1.1 엔드포인트:
  * GET [https://api.x.com/1.1/blocks/ids.json](https://api.x.com/1.1/blocks/ids.json)
    (지정된 사용자가 차단한 사용자 ID 목록)
  * GET [https://api.x.com/1.1/blocks/lists.json](https://api.x.com/1.1/blocks/lists.json)
    (지정된 사용자가 차단한 사용자 목록)
* X API v2 엔드포인트:
  * GET [https://api.x.com/2/users/:id/blocking](https://api.x.com/2/users/:id/blocking)
    (지정된 사용자 ID가 차단한 사용자 목록)
     

**요청당 사용자 수 제한**

Standard v1.1 엔드포인트는 요청당 최대 5000명의 사용자를 반환할 수 있습니다. 새로운 v2 엔드포인트는 요청당 최대 1000명의 사용자를 반환할 수 있습니다. 한 번에 1000명의 사용자를 모두 반환받으려면 쿼리 매개변수로 `max_results=1000`을 전달해야 합니다. 그런 다음 응답 페이로드에 포함된 `next_token`을 다음 요청에서 `pagination_token` 쿼리 매개변수로 전달할 수 있습니다.
 

**App 및 Project 요구 사항**

X API v2 엔드포인트는 요청을 인증할 때 [developer App](/ko/resources/fundamentals/developer-apps)과 [Project](/ko/resources/fundamentals/developer-apps)에 연결된 자격 증명을 사용해야 합니다. 모든 X API v1.1 엔드포인트는 Project에 연결되지 않은 App 또는 Project에 연결된 App의 자격 증명을 사용할 수 있습니다.

**응답 데이터 형식**

Standard v1.1과 X API v2 엔드포인트 버전 간의 가장 큰 차이점 중 하나는 페이로드에 어떤 필드를 반환할지 선택하는 방식입니다.

Standard 엔드포인트의 경우, 많은 응답 필드를 기본값으로 받게 되며, 이후 매개변수를 사용해 페이로드에 반환되어야 하는 필드 또는 필드 집합을 지정할 수 있습니다.

X API v2 버전은 기본적으로 사용자 `id`, `name`, `username` 필드만 제공합니다. 추가 필드나 객체를 요청하려면 [fields](/ko/x-api/fundamentals/fields) 및 [expansions](/ko/x-api/fundamentals/expansions) 매개변수를 사용해야 합니다. 이 엔드포인트에서 요청한 모든 사용자 필드는 기본 사용자 객체에 포함되어 반환됩니다. 확장된 게시물 객체와 필드는 응답 내 `includes` 객체에 포함되어 반환됩니다. 그런 다음 사용자와 확장된 게시물 객체 둘 다에 있는 ID를 매칭하여, 확장된 객체를 다시 사용자 객체와 연결할 수 있습니다. 

이러한 새 매개변수에 대해 더 자세히 알아보려면 각 매개변수에 대한 가이드를 참고하거나, [필드와 expansions를 사용하는 방법](/ko/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions)에 대한 가이드를 읽어 보시기 바랍니다. 

또한 standard v1.1 필드를 최신 v2 필드로 매핑하는 데 도움이 되는 [데이터 형식 마이그레이션 가이드](/ko/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2)를 준비했습니다. 이 가이드는 v2 요청에서 특정 필드를 반환하기 위해 전달해야 하는 구체적인 expansion 및 필드 매개변수도 제공합니다. 
 

특정 필드를 요청하는 방식의 변경 사항 외에도, X API v2는 API가 반환하는 객체를 위한 새로운 JSON 설계를 도입하고 있으며, 여기에는 [P](/ko/x-api/fundamentals/data-dictionary#tweet)ost 및 [user](/ko/x-api/fundamentals/data-dictionary#user) 객체가 포함됩니다.

* JSON 루트 레벨에서, standard 엔드포인트는 `statuses` 배열에 게시물 객체를 반환하는 반면, X API v2는 `data` 배열을 반환합니다. 
* Retweeted 및 Quoted "statuses"를 참조하는 대신, X API v2 JSON은 Retweeted 및 Quoted Tweet을 참조합니다. `contributors`, `user.translator_type`과 같이 레거시이거나 더 이상 사용되지 않는 많은 필드는 제거됩니다. 
* 게시물 객체의 `favorites`와 사용자 객체의 `favourites`를 모두 사용하는 대신, X API v2는 `like`라는 용어를 사용합니다. 
* X는 값이 없는 JSON 값(예: `null`)은 페이로드에 기록하지 않는 관례를 채택하고 있습니다. 게시물 및 사용자 속성은 null이 아닌 값을 가질 때만 포함됩니다. 
   

또한 다음을 포함하여 [Post object](/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 요청 파라미터는 두 개의 쿼리 매개변수(`user_id` 또는 `screen_name`)를 허용했습니다. X API v2에서는 숫자형 사용자 ID만 허용하며, 이 값은 엔드포인트 경로에 포함하여 전달해야 합니다.

***

<div id="code-examples">
  ## 코드 예제
</div>

<div id="get-blocked-users-v2">
  ### 차단한 사용자 조회 (v2)
</div>

<CodeGroup dropdown>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/123456789/blocking?user.fields=username,verified&max_results=100" \
    -H "Authorization: OAuth ..."
  ```

  ```python Python theme={null}
  # OAuth 1.0a 사용자 컨텍스트 인증이 필요합니다
  import requests
  from requests_oauthlib import OAuth1

  auth = OAuth1(
      "API_KEY", "API_SECRET",
      "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET"
  )

  url = "https://api.x.com/2/users/123456789/blocking"
  params = {"user.fields": "username,verified", "max_results": 100}

  response = requests.get(url, auth=auth, params=params)
  print(response.json())
  ```

  ```python Python SDK theme={null}
  from xdk import Client
  from xdk.oauth1_auth import OAuth1

  oauth1 = OAuth1(
      api_key="YOUR_API_KEY",
      api_secret="YOUR_API_SECRET",
      access_token="YOUR_ACCESS_TOKEN",
      access_token_secret="YOUR_ACCESS_TOKEN_SECRET"
  )

  client = Client(auth=oauth1)

  # 페이지네이션을 사용해 차단한 사용자 목록 가져오기
  for page in client.users.get_blocking(
      "123456789",
      user_fields=["username", "verified"],
      max_results=100
  ):
      for user in page.data:
          print(f"{user.username} - Verified: {user.verified}")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client, OAuth1 } from "@xdevplatform/xdk";

  const oauth1 = new OAuth1({
    apiKey: "YOUR_API_KEY",
    apiSecret: "YOUR_API_SECRET",
    accessToken: "YOUR_ACCESS_TOKEN",
    accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET",
  });

  const client = new Client({ oauth1 });

  // 페이지네이션을 사용해 차단한 사용자 목록 가져오기
  const paginator = client.users.getBlocking("123456789", {
    userFields: ["username", "verified"],
    maxResults: 100,
  });

  for await (const page of paginator) {
    page.data?.forEach((user) => {
      console.log(`${user.username} - Verified: ${user.verified}`);
    });
  }
  ```
</CodeGroup>

<div id="block-a-user-v2">
  ### 사용자 차단 (v2)
</div>

<CodeGroup dropdown>
  ```bash cURL theme={null}
  curl -X POST "https://api.x.com/2/users/123456789/blocking" \
    -H "Authorization: OAuth ..." \
    -H "Content-Type: application/json" \
    -d '{"target_user_id": "2244994945"}'
  ```

  ```python Python theme={null}
  # OAuth 1.0a 사용자 컨텍스트 인증이 필요합니다
  import requests
  from requests_oauthlib import OAuth1

  auth = OAuth1(
      "API_KEY", "API_SECRET",
      "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET"
  )

  url = "https://api.x.com/2/users/123456789/blocking"
  response = requests.post(url, auth=auth, json={"target_user_id": "2244994945"})
  print(response.json())
  ```

  ```python Python SDK theme={null}
  from xdk import Client
  from xdk.oauth1_auth import OAuth1

  oauth1 = OAuth1(
      api_key="YOUR_API_KEY",
      api_secret="YOUR_API_SECRET",
      access_token="YOUR_ACCESS_TOKEN",
      access_token_secret="YOUR_ACCESS_TOKEN_SECRET"
  )

  client = Client(auth=oauth1)

  # 사용자를 차단합니다
  response = client.users.block(
      source_user_id="123456789",
      target_user_id="2244994945"
  )
  print(f"Blocking: {response.data.blocking}")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client, OAuth1 } from "@xdevplatform/xdk";

  const oauth1 = new OAuth1({
    apiKey: "YOUR_API_KEY",
    apiSecret: "YOUR_API_SECRET",
    accessToken: "YOUR_ACCESS_TOKEN",
    accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET",
  });

  const client = new Client({ oauth1 });

  // 사용자를 차단합니다
  const response = await client.users.block("123456789", {
    targetUserId: "2244994945",
  });
  console.log(`Blocking: ${response.data?.blocking}`);
  ```
</CodeGroup>