> ## Documentation Index > Fetch the complete documentation index at: https://docs.x.com/llms.txt > Use this file to discover all available pages before exploring further. # 認証付きリクエストの実行 > OAuth 1.0a を用いて HTTPS で認証付きの X Ads API リクエストを実行する方法。Twurl のセットアップ、HTTP verbs、インラインパラメーター、URL エンコードのルールなどを解説します。 X Ads API エンドポイントへのアクセスには、アプリケーションが TLS を用いて [https://ads-api.x.com](https://ads-api.x.com) に対して安全に認証付き Web リクエストを送信することが必要です。 以下のセクションでは、認証付き API リクエストの概要、API を操作するための [Twurl](https://github.com/twitter/twurl#getting-started) のセットアップ、OAuth 1.0a をサポートするためにアプリケーションを拡張して Ads アカウントに対するリクエストを行う方法を説明します。 ## 要件 X Ads API に認証付きリクエストを行う前に、以下が必要です。 * [承認済みのデベロッパーアカウント](/resources/fundamentals/developer-portal) * [Ads API アクセスが承認された](/x-ads-api/introduction)アプリケーション * [アプリ管理 UI](/resources/fundamentals/developer-apps) を通じて取得した API key および secret * X Ads アカウントへのアクセス権を持つユーザーの[アクセストークン](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) ## API の利用 Advertising API は [https://ads-api.x.com](https://ads-api.x.com) でアクセスします。[standard REST API](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/overview) と Advertising API は、同じクライアントアプリで併用できます。Advertising API は HTTPS を必須とするため、HTTP でエンドポイントにアクセスしようとするとエラーメッセージが返されます。 Ads API は JSON を出力します。すべての識別子は文字列であり、すべての文字列は UTF-8 です。Advertising API は[バージョン管理](/x-ads-api/fundamentals/versioning)されており、バージョンは任意のリソース URL の最初のパス要素として指定します。 `https://ads-api.x.com//accounts` ## HTTP verbs と一般的なレスポンスコード Ads API では 4 つの HTTP verb が使用されます。 * **GET** はデータを取得します * **POST** は新しいデータ(キャンペーンなど)を作成します * **PUT** は既存のデータ(line item など)を更新します * **DELETE** はデータを削除します。 削除は恒久的ですが、削除されたデータは、リソースをリクエストする際に明示的に `with_deleted=true` パラメーターを含めることで、ほとんどの GET ベースのメソッドから引き続き閲覧できます。それ以外の場合、削除されたレコードは HTTP 404 を返します。 成功したリクエストでは、リソースを作成、削除、または更新した際に、そのオブジェクトを表す JSON レスポンスとともに HTTP 200 系のレスポンスが返されます。 HTTP PUT でデータを更新する場合、指定されたフィールドのみが更新されます。任意の値を解除するには、そのパラメーターに空文字列を指定します。たとえば、以下のパラメーター群は、指定済みの `end_time` を解除します: `&end_time=&paused=false`。 エラーレスポンスの詳細については [Error Codes & Responses](/x-ads-api/fundamentals/error-codes-and-responses) を参照してください。 ## インラインパラメーター ほとんどのリソース URL には 1 つ以上のインラインパラメーターが含まれます。多くの URL はクエリ文字列、または POST/PUT リクエストではボディに、明示的に宣言されたパラメーターも受け付けます。 インラインパラメーターは、各リソースの **Resource Path** セクションで先頭に付いたコロン(":")で示されます。たとえば、対象のアカウントが `"abc1"` として識別され、[アカウントに関連付けられたキャンペーンを取得](/x-ads-api/campaign-management/reference#campaigns)している場合、URL `https://ads-api.x.com/6/accounts/abc1/campaigns` を使用してそのリストにアクセスします。リソース URL(`https://ads-api.x.com/6/accounts/:account_id/campaigns`)で説明されているインラインの `account_id` パラメーターを指定することで、リクエストのスコープをそのアカウントに関連するオブジェクトのみに絞り込んでいます。 ## アクセストークンの使用 X Ads API は、署名付き HTTPS リクエストを使用してアプリケーションの ID を検証し、さらに、アプリケーションが API リクエストを代行するエンドユーザーに付与された権限(ユーザーのアクセストークンで表現)を取得します。Ads API へのすべての HTTP 呼び出しは、HTTPS プロトコル上で(OAuth 1.0a を使用した)Authorization リクエストヘッダーを含む必要があります。 X Ads API との統合のために、OAuth 1.0a の Authorization リクエストヘッダーを生成する機能をアプリケーションに追加する必要があります。ただし、署名付きリクエストの生成は複雑なため、パートナーには X API をサポートするか OAuth 1.0a のリクエスト処理を実装している既存のライブラリを使用することを強く推奨します。[推奨 OAuth ライブラリ](/resources/fundamentals/authentication#oauth-1-0a-2)および[認証コードサンプル](/resources/fundamentals/authentication#oauth-1-0a-2)のリストをご覧ください。 既知のライブラリを使用中に認証エラーが発生したパートナーには支援できますが、独自の OAuth 実装はサポートできない点にご注意ください。 ## HTTP と OAuth X REST API v1.1 と同様、Advertising API は [OAuth 1.0A](/resources/fundamentals/authentication) と HTTPS の両方の使用を必須とします。API キーは[アプリ管理コンソール](/resources/fundamentals/developer-apps)から取得できます。「current user」を表すためにアクセストークンも使用する必要があります。current user とは、広告機能を持つ X アカウントのことです。 パートナーは独自に実装するのではなく、OAuth ライブラリを使用することを強く推奨します。既知のライブラリの使用時にはデバッグをサポートできますが、独自の OAuth 実装を用いる場合はサポートできません。使用できる[ライブラリ](/resources/fundamentals/authentication#oauth-1-0a-2)をご覧ください。 API は HTTP 1.1 と OAuth に対して厳密です。OAuth 署名ベース文字列を準備する前に、URL や POST ボディ内の[予約文字を適切にエンコード](https://tools.ietf.org/html/rfc3986#section-2.2)していることを確認してください。特に Advertising API では、時間指定時に「:」文字を、複数オプションのコレクションを提供する際に「,」文字を使用します。これら両方は、次の予約セットに含まれます。 | Symbol | URL Encoded | | :----- | :---------- | | ! | %21 | | # | %23 | | \$ | %24 | | & | %26 | | ' | %27 | | ( | %28 | | ) | %29 | | \* | %2A | | + | %2B | | , | %2C | | / | %2F | | : | %3A | | ; | %3B | | = | %3D | | ? | %3F | | @ | %40 | | \[ | %5B | | ] | %5D | ## Twurl で最初の API リクエストを行う X は、[cURL](https://en.wikipedia.org/wiki/CURL) の代替として OAuth 1.0a の Authorization ヘッダーをサポートするコマンドラインツール [Twurl](https://developer.x.com/en/docs/tutorials/using-twurl) の維持を支援しています。Twurl は、認証付き API リクエストを行うシンプルな方法を提供し、アプリケーションに認証を追加する前に Ads API を試すのに役立ちます。 [Twurl のインストールと認可](https://github.com/twitter/twurl#getting-started)を行うと、素早くアクセストークンを生成し、Ads API に対して認証付きリクエストを行えます。 ```bash theme={null} twurl -H "ads-api.x.com" "/5/accounts/" ``` API 経由でキャンペーンを作成する[ステップバイステップ](/x-ads-api/campaign-management/reference#creating-a-campaign-step-by-step) チュートリアルに沿って、Twurl と API に慣れる時間を取ってください。 ## Postman でテストする コマンドラインツールに慣れていない方のために、X Ads API エンドポイント向けの Postman コレクションもご用意しています。 [Postman](https://www.getpostman.com/products) は、今日の業界で最も人気のある API 開発ツールの 1 つです。優れたユーザーインターフェースを持つ HTTP クライアントで、複雑な API リクエストをより簡単に行えるようにし、生産性を高めます。 Postman のインストールと Ads API Postman コレクションの使用を始めるには、[セットアップガイド](https://github.com/xdevplatform/postman-twitter-ads-api#installation)をご覧ください。 ### アプリケーションを拡張して認証付きリクエストを行う Twurl を使って Ads API にリクエストを行うことに慣れたら、次はアプリケーションに OAuth 1.0a 認証ヘッダーを生成するサポートを追加します。 [OAuth 1.0a](/resources/fundamentals/authentication) 認証ヘッダーには、アプリケーションおよびユーザーの ID を検証し、リクエストの改ざんを防止するための情報が含まれます。アプリケーションは、各 API リクエストに対して新しい Authorization ヘッダーを作成する必要があります。多くの言語には、X に API リクエストを行うためのこの authorization ヘッダー作成をサポートするオープンソースライブラリがあります。 以下は、C#、PHP、Ruby、Python の例です — [コードサンプル](/resources/fundamentals/authentication#oauth-1-0a-2)。 ## カスタム実装 一部のシナリオでは、オープンソースライブラリのサポートなしで OAuth 1.0a 認証を実装する必要があります。[Authorizing a request](/resources/fundamentals/authentication#authorizing-a-request) には、Authorization ヘッダー作成のサポートを実装する詳細な手順が記載されています。コミュニティサポートされたライブラリを使用することを強くおすすめします。 一般的な手順: 1. ヘッダー用の 7 つのキー/値ペアを収集する — oauth\_ で始まるもの 2. それらのキー/値ペアを用いて [OAuth 1.0a HMAC-SHA1 署名](/resources/fundamentals/authentication#creating-a-signature)を生成する 3. 上記の値を用いて [Authorization ヘッダー](/resources/fundamentals/authentication#authorizing-a-request)を構築する