시작하기

이 페이지에는 개발자가 애드센스 호스트 API를 사용하여 애드센스 계정에 대한 정보를 조회하는 방법이 나와 있습니다. 여기에 나오는 내용을 이해하려면 웹 프로그래밍 개념 및 웹 데이터 형식에 대한 지식이 필요합니다.

목차

시작하기 전에 해야 할 일

애드센스 계정 만들기

테스트용으로 사용할 애드센스 계정이 필요합니다. 이미 테스트 계정이 있다면 애드센스 사용자 인터페이스에서 바로 테스트 데이터를 설정, 수정 또는 확인할 수 있습니다.

애드센스 이해하기

애드센스 소개 자료를 읽고 애드센스의 기본 개념을 이해하고, 사용자 인터페이스를 둘러본 다음 코드를 작성하시기 바랍니다.

애플리케이션 등록

애드센스 호스트 API를 이용하려면 개발 중인 애플리케이션을 Google에 등록해야 합니다.

  1. API 콘솔로 이동합니다.
  2. Google 계정에 로그인하거나 새 계정을 만듭니다.
  3. 새 프로젝트를 만듭니다.
  4. 새로 만든 프로젝트에서 애드센스 호스트 API 아래에 있는 '액세스 요청' 링크를 클릭합니다.

OAuth 2.0 애플리케이션의 경우 OAuth 2.0를 이용하여 Google API에 액세스하기에 나온 추가 단계를 따르세요.

참고: 등록 시 사용하는 Google 계정은 귀하의 개발자 계정이어야 합니다. 즉, 이 애플리케이션의 사용자들에게 애플리케이션 개발자로 알리고픈 계정이어야 합니다. 애플리케이션 사용 시 각 사용자는 개인 계정에 액세스 권한을 부여하게 되므로, 이 계정을 애드센스 로그인용으로 지정하지 않아도 됩니다.

애드센스 호스트 API 이해하기

기본 개념

애드센스 호스트 API는 애드센스의 기본 개념을 바탕으로 만들어졌습니다.

  • 광고 클라이언트: 광고 클라이언트는 애드센스 계정과 애드센스 제품(예: 콘텐츠 광고 또는 검색 광고) 간의 관계를 표시합니다. 애드센스 계정 하나에서 하나 이상의 광고 클라이언트를 가질 수 있습니다.
  • 채널: 채널은 특정 페이지 또는 도메인의 실적을 추적할 수 있는 도구입니다.
  • 보고서: 보고서를 통해 수입 내역 및 이러한 수입에 영향을 미친 요소 등에 대한 정보를 자세히 파악할 수 있습니다. 계정 전체에 대한 보고서를 실행하거나 채널을 사용하여 특정 인벤토리에 대한 보고서를 실행할 수 있습니다.

지원되는 연산

아래 표에 현재 API에서 지원되는 연산이 나와 있습니다.

연산 설명 REST HTTP 매핑
list 컬렉션 하나에 있는 모든 리소스를 나열합니다. 컬렉션 URI의 GET
get 특정 리소스를 가져옵니다. 리소스 URI의 GET
generate 지정된 리소스를 바탕으로 결과 조합을 생성하며, 보고서에만 사용됩니다. 컬렉션 URI의 GET/POST. 여기에서 리소스를 생성에 대한 정의로 전달합니다.

모든 연산은 인증이 필요합니다.

호출 스타일

REST는 데이터 요청 및 수정에 대한 간편하고 일관적인 접근 방식을 제공하는 소프트웨어 아키텍처의 한 스타일입니다.

REST는 'Representational State Transfer'의 줄임말로, Google API의 맥락에서 REST는 HTTP 동사를 사용하여 Google이 저장한 데이터 표현을 검색 및 수정하는 방법을 의미합니다.

REST식 시스템에서는 리소스가 데이터 저장소에 저장되고, 클라이언트는 서버에서 특정 작업(리소스 생성, 검색, 업데이트, 삭제 등)을 수행하라는 요청을 전송하며, 서버는 작업을 수행하고 응답을 전송합니다. 이 응답은 지정된 리소스 표현의 형식을 취하는 경우가 많습니다.

Google의 REST식 API에서는 클라이언트가 POST, GET, PUT 또는 DELETE 등의 HTTP 동사를 사용하여 작업을 지정합니다. 리소스를 지정할 때 다음과 같은 형식의 고유한 URI를 사용합니다.

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

모든 API 리소스에는 HTTP에서 액세스할 수 있는 고유 URI가 있으므로 REST는 데이터 캐싱을 지원하며 웹의 분산형 인프라와의 연동성이 뛰어납니다.

REST에 대한 자세한 내용은 아래의 외부 문서를 참조하세요.

  • Building Web Services the REST Way - REST 방식으로 웹 서비스 구축하기. 서비스 제공업체를 위한 자료이나 REST에 대한 개요를 잘 설명하고 있음.
  • HTTP 1.1 메소드 정의 - GET, POST, PUTDELETE의 사양이 설명되어 있음

애드센스 호스트 API의 REST

애드센스 호스트 API 연산에 설명된 대로 지원되는 연산이 해당 REST HTTP 동사에 직접 매핑됩니다.

애드센스 호스트 API URI에서 사용하는 형식은 다음과 같습니다.

https://www.googleapis.com/adsensehost/v4.1/resourceID?parameters

여기서 resourceID는 광고 클라이언트, 광고 단위, URL 채널, 맞춤 채널 또는 보고서 컬렉션의 ID이며, parameters는 쿼리에 적용되는 매개변수입니다.

resource ID 형식의 경로 확장을 통해 현재 연산의 리소스를 지정할 수 있습니다. 예를 들면 다음과 같습니다.

https://www.googleapis.com/adsensehost/v4.1/adclients
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId/urlchannels
...

API에서 지원되는 각 작업에 사용되는 전체 URI 집합은 애드센스 호스트 API 참조 문서에 요약되어 있습니다.

다음은 애드센스 호스트 API에서 전체 URL 집합이 작동하는 방식의 예입니다.

광고 클라이언트 나열:

GET https://www.googleapis.com/adsensehost/v4.1/adclients/

데이터 형식

JSON(JavaScript Object Notation)은 특정 언어에 의존하지 않는 일반적인 데이터 형식으로, 임의의 데이터 구조를 간단한 텍스트로 표현할 수 있습니다. 자세한 내용은 json.org 사이트를 참조하세요.

요청하기

요청 승인하기

애플리케이션에서 애드센스 호스트 API로 전송하는 모든 요청에는 승인 토큰이 포함되어야 합니다. 또한 이 토큰이 있어야 Google에서 애플리케이션을 식별할 수 있습니다.

승인 프로토콜 정보

애플리케이션은 요청을 승인하기 위해 OAuth 2.0을 사용해야 합니다. 다른 승인 프로토콜은 지원되지 않습니다.

OAuth 2.0으로 요청 승인

애드센스 호스트 API에 대한 모든 요청은 인증된 사용자의 승인을 받아야 합니다.

OAuth 2.0의 자세한 승인 과정 또는 '절차'는 개발하는 애플리케이션의 종류에 따라 조금씩 다릅니다. 일반적으로 다음과 같은 과정을 거치게 됩니다.

  1. 애플리케이션을 만들 때 Google Developers Console을 사용하여 등록합니다. 이렇게 하면 Google에서 고객 ID 및 고객 암호와 같이 나중에 필요한 정보를 제공합니다.
  2. Google Developers Console에서 애드센스 호스트 API v4를 활성화합니다. Developers Console의 목록에 해당 API가 없는 경우 이 단계를 건너뛰세요.
  3. 애플리케이션에서 사용자 데이터에 액세스해야 할 경우 Google에 특정 범위의 액세스를 요청합니다.
  4. Google은 사용자에게 동의 화면을 표시하며, 사용자 데이터 일부를 요청하는 애플리케이션을 승인할 것인지 묻습니다.
  5. 사용자가 요청을 승인하면 Google은 애플리케이션에 한시적인 액세스 토큰을 제공합니다.
  6. 애플리케이션에서 사용자 데이터를 요청할 때 이 액세스 토큰을 첨부합니다.
  7. Google은 애플리케이션의 요청과 토큰이 유효한 것으로 판단될 경우 요청된 데이터를 반환합니다.

경우에 따라 토큰 갱신을 사용하여 새 액세스 토큰을 가져오는 등의 추가 단계를 거쳐야 할 수 있습니다. 애플리케이션 유형별 승인 과정에 대한 자세한 내용은 Google의 OAuth 2.0 설명서를 참조하세요.

다음은 애드센스 호스트 API의 OAuth 2.0 액세스 범위 정보입니다.

범위 의미
https://www.googleapis.com/auth/adsensehost 애드센스 데이터에 대한 읽기/쓰기 액세스입니다.

OAuth 2.0을 사용하여 액세스를 요청하려면 애플리케이션에 범위 정보와 애플리케이션 등록 시 Google이 제공하는 정보(예: 고객 ID 및 고객 암호)가 있어야 합니다.

도움말: Google API 클라이언트 라이브러리는 승인 과정 중 일부를 자동으로 처리할 수 있습니다. 여러 가지 프로그래밍 언어로 제공되므로 자세한 내용은 라이브러리 및 예제 페이지를 참조하세요.

자세히 알아보려면 OAuth 2.0 섹션을 참조하세요.

요청 만들기

마지막 단계는 API 요청 만들기입니다. 클라이언트 라이브러리를 사용하지 않을 경우 참고 자료를 참조하시기 바랍니다.

클라이언트 라이브러리를 사용하면 작업이 매우 쉬워집니다. 자바, Python, PHP 또는 자바스크립트 클라이언트 라이브러리를 사용하여 첫 요청을 하는 방법에 대해 자세히 알아보려면 샘플 및 라이브러리를 참조하세요.

OAuth 2.0

애드센스 호스트 API에서 인증과 승인은 OAuth 2.0에 의해 처리됩니다. 하지만 애드센스 호스트 사용 모델의 일부 특징으로 인해 처리 방식은 다른 Google API와 약간 다릅니다.

참여자

OAuth 2.0 요청에는 다음과 같은 3명의 참여자가 있습니다.

  • 사용자. 개인 데이터에 액세스 권한을 부여함
  • 개발자. 신청 과정에서 사용자 데이터에 대한 액세스 권한을 요청함
  • Google. 사용자와 개발자를 인증하고 API 서비스를 제공함

그러나 애드센스 호스트 API에서는 개발자가 API를 사용하여 자신의 애드센스 계정에 대한 액세스 권한을 얻고 이를 통해 게시자의 계정에 대한 액세스 권한을 얻으므로 사용자와 개발자는 실질적으로 동일인입니다.

프로젝트 만들기

API 콘솔 페이지에서 새 프로젝트를 만들 수 있습니다.
그림 1: API 콘솔의 새 프로젝트

먼저 다른 Google API에서처럼 API 콘솔에서 새 프로젝트를 만들어야 합니다. 개발자 프로젝트를 만들기 위해 사용하는 Google 계정은 애드센스 호스트 API에 액세스가 허용되어야 합니다. 따라서 Google이 가입 과정에서 만든 샌드박스 계정을 사용하거나, API 구현을 완료하여 라이브 구현까지 마친 경우에는 제작 애드센스 계정을 사용하세요.

서비스 탭에서 프로젝트의 활성 API를 선택할 수 있습니다.
그림 2: 프로젝트에서 사용 중이거나 사용중지된 API

Google API 프로젝트 만들기에 대해 자세히 알아보려면 API 콘솔 안내서를 참조하세요.

API 액세스 설정하기

프로젝트를 만들었으면 OAuth 2.0 클라이언트 ID를 생성하여 API 액세스를 설정해야 합니다.

API 액세스 탭에서 OAuth 2.0 클라이언트를 만들 수 있습니다.
그림 3: API 콘솔에서 새로운 OAuth 2.0 클라이언트 만들기

선택할 수 있는 방법은 여러 개지만 후속 단계가 더 쉬운 설치된 애플리케이션 프로젝트를 만드시기 바랍니다.

한 번 인증 후 영구 저장

이제 자신의 애드센스 계정을 이용하여 인증 작업을 해야 합니다. 이 단계는 작은 스크립트나 테스트 애플리케이션을 이용해 진행할 수 있습니다(예를 보려면 애드센스의 샘플 코드 참조).

인증 후에는 승인 단계에서 다시 받은 새로고침 토큰을 저장해야 합니다. 이 토큰은 액세스 권한이 명시적으로 취소되지 않는 한 유효기간 없이 오랫동안 사용할 수 있습니다. 사용자는 자신의 애플리케이션에 대한 액세스 권한을 취소해서는 안 됩니다.

차후의 인증 요청에 대비해 애플리케이션의 데이터 저장소에 새로고침 토큰을 저장하세요.

애플리케이션에서 저장된 토큰 이용하기

새로고침 토큰을 일단 가지게 되면 이 토큰이 웹 서버 애플리케이션 과정과 설치된 애플리케이션 과정 중 어디에서 생성되었는지는 더 이상 중요하지 않습니다. 이제는 필요에 따라 새로운 액세스 토큰에 토큰 새로고침 요청을 할 때 이 토큰을 사용하기만 하면 됩니다. 클라이언트 라이브러리 중 하나를 사용 중이라면 해당 도움말에서 자신의 토큰을 지정하는 방법에 대해 알아보시기 바랍니다. 자동으로 생성된 파일이나 데이터베이스 입력값은 수정이 필요할 수도 있습니다.

결론

최종 결론은 OAuth 2.0 과정은 한 번만 실행되며, 모든 요청이 백그라운드에서 발생한 후에는 사이트(게시자)의 최종 사용자나 개발자의 직접 개입 없이 실행된다는 점입니다.

공지사항

애드센스 API 소식에서 새 버전, 새 기능, 주요 서비스 업데이트 등을 수시로 확인하세요.

다음에 대한 의견 보내기...

AdSense Host API
AdSense Host API