連携ガイド

ポストルックアップ連携のための基本概念とベストプラクティス

このガイドでは、ポスト取得エンドポイントをアプリケーションに統合するために必要な主要な概念を説明します。

---

​

認証

すべての X API v2 エンドポイントでは認証が必要です。ユースケースに合った方法を選択してください。

方法	最適な用途	プライベートメトリクスへのアクセス可否
OAuth 2.0 App-Only	サーバー間連携、公開データ	いいえ
OAuth 2.0 Authorization Code with PKCE	ユーザー向けアプリケーション	はい (認可されたユーザーの投稿)
OAuth 1.0a User Context	レガシー統合	はい (認可されたユーザーの投稿)

​

App-only 認証

公開投稿データにはベアラートークンを使用します。

cURL

shellscript

curl "https://api.x.com/2/tweets/1234567890" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​

User Context 認証

非公開メトリクスにアクセスするには、ポストの作成者として認証を行ってください。

次のフィールドを利用するには User Context 認証が必要です:

• tweet.fields.non_public_metrics
• tweet.fields.promoted_metrics
• tweet.fields.organic_metrics
• media.fields.non_public_metrics
• media.fields.promoted_metrics
• media.fields.organic_metrics

---

​

フィールドとexpansions

X API v2 はデフォルトでは最小限のデータのみを返します。fields と expansions を指定して、必要な情報だけをリクエストしてください。

​

既定のレスポンス

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "edit_history_tweet_ids": ["1234567890"]
  }
}

​

利用可能なフィールド

tweet.fields

Field	Description
created_at	ポストの作成タイムスタンプ
author_id	ポスト作成者のユーザーID
public_metrics	いいね、リポスト、返信、引用の数
entities	ハッシュタグ、メンション、URL、キャッシュタグ
attachments	メディアキー、投票ID
conversation_id	スレッド識別子
context_annotations	トピック／エンティティの分類情報
in_reply_to_user_id	返信先ユーザーのID
lang	検出された言語
source	投稿元クライアント
possibly_sensitive	センシティブコンテンツのフラグ
reply_settings	誰が返信できるかの設定

user.fields (requires author_id expansion)

Field	Description
username	@ユーザー名
name	表示名
profile_image_url	プロフィール画像のURL
verified	認証ステータス
description	自己紹介
public_metrics	フォロワー数／フォロー数
created_at	アカウント作成日

media.fields (requires attachments.media_keys expansion)

Field	Description
url	メディアURL
preview_image_url	サムネイルURL
type	photo、video、animated_gif
duration_ms	動画の再生時間
height, width	縦横サイズ
alt_text	アクセシビリティ向けテキスト

​

フィールドを指定した例

cURL

shellscript

curl "https://api.x.com/2/tweets/1234567890?\
tweet.fields=created_at,public_metrics,entities&\
expansions=author_id,attachments.media_keys&\
user.fields=username,verified&\
media.fields=url,type" \
  -H "Authorization: Bearer $BEARER_TOKEN"

---

​

ポストの編集

投稿は作成してから30分以内で最大5回まで編集できます。

​

仕組み

• 各編集で新しいポストIDが発行されます
• edit_history_tweet_ids にはすべてのバージョン (古い順) が含まれます
• このエンドポイントは常に最新バージョンを返します

​

レスポンスの例

{
  "data": {
    "id": "1234567893",
    "text": "Hello world! (edited twice)",
    "edit_history_tweet_ids": [
      "1234567890",
      "1234567891",
      "1234567893"
    ]
  }
}

30 分間の編集ウィンドウを過ぎてから取得された投稿は、その最終版を表します。リアルタイムのユースケースでは、公開された直後の投稿は、まだ編集中である可能性がある点に注意してください。

---

​

エラー処理

​

一般的なエラー

Status	エラー	対処方法
400	無効なリクエスト	パラメータの形式を確認する
401	未認証	認証情報を確認する
403	アクセス禁止	App の権限を確認する
404	見つかりません	ポストが削除されているか、存在していません
429	リクエスト過多	待機してから再試行する (レート制限を参照)

​

削除されたポストまたは保護されたポスト

ポストが削除されているか、自分がフォローしていない保護されたアカウントのポストである場合は:

• 単一ポストルックアップは 404 を返します
• 複数ポストルックアップでは、そのポストは結果から除外され、errors 配列が返されます

{
  "data": [
    { "id": "1234567890", "text": "Available post" }
  ],
  "errors": [
    {
      "resource_id": "1234567891",
      "resource_type": "tweet",
      "title": "Not Found Error",
      "detail": "Could not find tweet with id: [1234567891]."
    }
  ]
}

---

​

ベストプラクティス

リクエストのバッチ処理

複数のポストを一度に最大100件まで取得できるエンドポイントを使用し、API呼び出し回数を削減します。

必要なフィールドのみをリクエスト

必要なフィールドだけを指定して、レスポンスのサイズと処理時間を最小限に抑えます。

レスポンスのキャッシュ

同じコンテンツに対する繰り返しリクエストを減らすために、ポストデータをローカルにキャッシュします。

編集への対応

リアルタイムなアプリケーションの場合は、30分の編集ウィンドウ後に投稿を再取得することを検討してください。

---

​

次のステップ

APIリファレンス

エンドポイントの完全なドキュメント

データディクショナリ

利用可能なすべてのオブジェクトとフィールド

サンプルコード

動作するコード例

エラー処理

エラーを適切に処理