메인 콘텐츠로 건너뛰기
X Ads API 엔드포인트에 액세스하려면 애플리케이션이 TLS를 사용해 https://ads-api.x.com 으로 보안 인증된 웹 요청을 전송해야 합니다. 다음 섹션에서는 인증된 API 요청 방식의 개요, API와 상호 작용하기 위한 Twurl 설정 방법, 그리고 애플리케이션을 확장하여 OAuth 1.0a를 지원하고 Ads 계정 대상으로 요청을 보내는 방법을 설명합니다.

​
요구 사항

X Ads API에 인증된 요청을 보내기 전에 다음이 필요합니다:

​
API 사용

Advertising API는 https://ads-api.x.com 에서 사용할 수 있습니다. 표준 REST API와 Advertising API는 동일한 클라이언트 앱에서 함께 사용할 수 있습니다. Advertising API는 HTTPS 사용을 요구하므로, HTTP로 엔드포인트에 접근하면 오류가 발생합니다. Ads API의 출력은 JSON입니다. 모든 식별자는 문자열이며, 모든 문자열은 UTF-8 인코딩입니다. Advertising API는 버전 관리를 사용하며, 버전은 모든 리소스 URL의 첫 번째 경로 요소로 지정됩니다. https://ads-api.x.com/<version>/accounts

​
HTTP 동사 및 일반적인 응답 코드

Ads API에서는 네 가지 HTTP 동사를 사용합니다:
  • GET은 데이터를 조회합니다
  • POST는 캠페인과 같은 새 데이터를 생성합니다
  • PUT은 라인 아이템과 같은 기존 데이터를 업데이트합니다
  • DELETE는 데이터를 삭제합니다.
삭제는 영구적이지만, 리소스를 요청할 때 with_deleted=true 파라미터를 명시적으로 포함하면 대부분의 GET 기반 메서드에서 삭제된 데이터를 계속 조회할 수 있습니다. 그렇지 않으면 삭제된 레코드는 HTTP 404를 반환합니다. 요청이 성공하면 리소스를 생성, 삭제 또는 업데이트할 때 해당 객체를 나타내는 JSON과 함께 HTTP 200대 응답이 반환됩니다. HTTP PUT으로 데이터를 업데이트할 때는 지정한 필드만 변경됩니다. 파라미터를 빈 문자열로 지정하여 선택적 값을 해제할 수 있습니다. 예를 들어, 다음 파라미터 그룹은 이미 지정된 end_time을 해제합니다. &end_time=&paused=false 오류 응답에 대한 자세한 내용은 Error Codes & Responses를 참조하세요.

​
인라인 매개변수

대부분의 리소스 URL에는 하나 이상의 인라인 매개변수가 포함됩니다. 많은 URL은 쿼리 문자열의 명시적 매개변수나, POST 또는 PUT 요청의 경우 본문 매개변수도 받습니다. 인라인 매개변수는 각 리소스의 Resource Path 섹션에서 앞에 콜론(”:”)을 붙여 표시됩니다. 예를 들어 작업 중인 계정의 식별자가 "abc1"이고 계정과 연결된 캠페인을 검색하려는 경우, https://ads-api.x.com/6/accounts/abc1/campaigns URL을 사용해 해당 목록에 접근할 수 있습니다. 리소스 URL(https://ads-api.x.com/6/accounts/:account_id/campaigns)에 설명된 인라인 account_id 매개변수를 지정하면, 요청 범위가 해당 계정과만 연결된 객체로 한정됩니다.

​
액세스 토큰 사용

X Ads API는 서명된 HTTPS 요청을 통해 애플리케이션의 신원을 검증하고, 애플리케이션이 대행하여 API 요청을 수행하는 최종 사용자가 부여한 권한을 확인합니다. 이 권한은 사용자의 액세스 토큰으로 표현됩니다. Ads API로의 모든 HTTP 호출에는 HTTPS 프로토콜을 통해 OAuth 1.0a를 사용하는 Authorization 요청 헤더가 포함되어야 합니다. X Ads API와 연동하려면 애플리케이션에 OAuth 1.0a Authorization 요청 헤더 생성 기능을 추가해야 합니다. 다만, 서명 요청 생성이 복잡하므로 X API를 지원하거나 OAuth 1.0a 요청 처리를 구현한 기존 라이브러리 사용을 강력히 권장합니다. 다음은 권장 OAuth 라이브러리 및 인증 코드 샘플 목록입니다. 검증된 라이브러리를 사용하면서 인증 오류가 발생한 경우에는 지원해 드리지만, 커스텀 OAuth 구현에 대해서는 지원하지 않습니다.

​
HTTP & OAuth

X REST API v1.1과 마찬가지로 Advertising API는 OAuth 1.0A와 HTTPS 사용을 요구합니다. API 키는 앱 관리 콘솔에서 발급할 수 있습니다. 액세스 토큰은 “현재 사용자”를 나타내기 위해서도 사용되어야 합니다. 현재 사용자는 광고 기능을 보유한 X 계정입니다. 직접 구현하기보다 OAuth 라이브러리를 사용할 것을 강력히 권장합니다. 검증된 라이브러리를 사용하는 경우에는 디버깅을 지원할 수 있지만, 자체 OAuth 구현에 대해서는 지원할 수 없습니다. 사용할 수 있는 라이브러리를 확인하세요. API는 HTTP/1.1과 OAuth 준수에 엄격합니다. OAuth 서명 베이스 문자열을 준비하기 전에 URL과 POST 본문에서 예약 문자 인코딩을 적절히 수행했는지 확인하세요. 특히 Advertising API는 시간을 지정할 때 “:” 문자를, 옵션 집합을 제공할 때 “,” 문자를 사용합니다. 두 문자는 모두 다음 예약 문자 집합에 포함됩니다:
SymbolURL Encoded
!%21
#%23
$%24
&%26
’%27
(%28
)%29
*%2A
+%2B
,%2C
/%2F
:%3A
;%3B
=%3D
?%3F
@%40
[%5B
]%5D

​
Twurl로 첫 API 요청 보내기

X는 cURL의 대안으로 OAuth 1.0a 인증 헤더를 지원하는 명령줄 도구 Twurl을 공동 유지관리합니다. Twurl은 애플리케이션에 인증을 통합하기 전에 인증된 API 요청을 손쉽게 보내고 Ads API를 살펴볼 수 있는 간단한 방법을 제공합니다. Twurl을 설치하고 권한을 부여한 후, 액세스 토큰을 빠르게 생성하고 Ads API에 인증된 요청을 보낼 수 있습니다. 
twurl -H "ads-api.x.com" "/5/accounts/"
API를 통해 캠페인을 생성하는 방법을 안내하는 이 단계별 튜토리얼을 따라 Twurl과 API에 익숙해지는 데 시간을 가져보세요.

​
Postman으로 테스트하기

명령줄 도구에 익숙하지 않은 분들을 위해 X Ads API 엔드포인트용 Postman 컬렉션도 제공합니다. Postman은 현재 업계에서 가장 널리 사용되는 API 개발 도구 중 하나입니다. 직관적인 사용자 인터페이스를 갖춘 HTTP 클라이언트로, 복잡한 API 요청을 더 쉽게 만들고 생산성을 높여줍니다. Postman을 설치하고 Ads API Postman 컬렉션 사용을 시작하려면 설정 가이드를 참조하세요.

​
인증된 요청을 수행하도록 애플리케이션 확장하기

Twurl로 Ads API 요청에 익숙해졌다면, 이제 애플리케이션에 OAuth 1.0a 인증 헤더 생성을 지원하도록 추가할 차례입니다. OAuth 1.0a 인증 헤더에는 애플리케이션과 사용자의 신원을 모두 검증하고, 요청 위변조를 방지하는 정보가 포함되어 있습니다. 애플리케이션은 각 API 요청마다 새로운 Authorization 헤더를 생성해야 합니다. 여러 프로그래밍 언어에 X로 API 요청을 보낼 때 이 인증 헤더 생성을 지원하는 오픈 소스 라이브러리가 있습니다. 다음은 C#, PHP, Ruby, Python을 사용하는 예시입니다 — 코드 샘플.

​
사용자 지정 구현

오픈 소스 라이브러리 없이 OAuth 1.0a 인증을 구현해야 하는 경우가 있습니다. 요청 권한 부여에서는 Authorization 헤더를 생성하도록 지원을 구현하는 방법을 자세히 설명합니다. 커뮤니티에서 검증된 라이브러리 사용을 강력히 권장합니다. 개요:
  1. 헤더용 7개의 key/value 쌍을 수집합니다(모두 oauth_로 시작)
  2. 해당 key/value 쌍을 사용해 OAuth 1.0a HMAC-SHA1 서명을 생성합니다
  3. 위 값들을 사용해 Authorization 헤더를 구성합니다