메인 콘텐츠로 건너뛰기
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 키는 App management console을 통해 얻을 수 있습니다. 액세스 토큰은 “현재 사용자”를 나타내기 위해서도 사용되어야 합니다. 여기서 현재 사용자는 광고 기능을 가진 X 계정을 의미합니다. 파트너는 직접 구현하기보다는 OAuth 라이브러리를 사용할 것을 강력히 권장합니다. 잘 알려진 라이브러리를 사용하는 경우에는 디버깅을 지원할 수 있지만, 자체 구현한 OAuth를 사용하는 경우에는 지원할 수 없습니다. 사용할 수 있는 라이브러리를 참고하십시오. 이 API는 HTTP/1.1 및 OAuth 규격을 엄격하게 따릅니다. OAuth 서명 베이스 문자열(signature base string)을 준비하기 전에, URL 및 POST 본문에서 예약 문자를 인코딩하고 있는지 적절히 확인하십시오. 특히 Advertising API는 시간을 지정할 때 ”:” 문자를, 옵션 집합을 제공할 때 ”,” 문자를 사용합니다. 이 두 문자는 모두 다음과 같은 예약 문자 집합에 속합니다:

Twurl로 첫 번째 API 요청 보내기

X는 명령줄 도구인 Twurl을 유지 관리하며, 이는 cURL의 대안으로 사용할 수 있고 OAuth 1.0a 인증 헤더를 지원합니다. Twurl은 인증된 API 요청을 보내고, 애플리케이션에 인증을 추가하기 전에 Ads API를 살펴보고 테스트해 볼 수 있는 간단한 방법을 제공합니다. Twurl을 설치하고 승인을 완료한 후에는 액세스 토큰을 빠르게 생성하고 Ads API에 인증된 요청을 보낼 수 있습니다.
Twurl과 API에 익숙해지기 위해, 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 요청을 보낼 때 필요한 Authorization 헤더 생성을 지원하는 오픈 소스 라이브러리를 제공합니다. 다음은 C#, PHP, Ruby, Python을 사용하는 몇 가지 예시입니다 - 코드 샘플.

커스텀 구현

일부 상황에서는 오픈 소스 라이브러리의 지원 없이 OAuth 1.0a 인증을 직접 구현해야 할 수 있습니다. 요청 권한 부여에서는 Authorization 헤더 생성을 지원하도록 구현하는 방법을 자세히 설명합니다. 커뮤니티에서 지원하는 라이브러리를 사용하는 것을 강력히 권장합니다. 일반적인 절차는 다음과 같습니다.
  1. 헤더에 사용할, 모두 oauth_로 시작하는 7개의 key/value 쌍을 수집합니다.
  2. 해당 key/value 쌍을 사용하여 OAuth 1.0a HMAC-SHA1 서명을 생성합니다.
  3. 위에서 얻은 값으로 Authorization 헤더를 작성합니다.