권장사항

이 페이지에서는 애드워즈 API 관련 애플리케이션 개발 시 고려해야 할 다양한 권장사항을 다루고 있습니다.

  1. 일반사항
    1. 여러 요청에서 인증 토큰을 재사용하세요.
    2. 2단계 인증 사용 시 애플리케이션 비밀번호의 누락 여부를 확인하세요.
    3. 여러 작업을 함께 묶어서 요청 횟수를 줄이세요.
    4. 작업을 타겟 광고그룹 또는 캠페인별로 나누어 분류하세요.
    5. 업데이트를 위해서는 스파스 객체를 보내세요.
    6. 오류를 처리하고 재시도하세요.
    7. 개발을 위해서 테스트 계정을 사용하세요.
    8. SOAP 메시지를 압축 파일로 만드세요.
    9. 부분 실패 기능을 활용하세요.
  2. 타겟팅 아이디어
    1. 'STATS' 요청에서는 키워드를 묶어 요청하세요.

일반사항

여러 요청에서 인증 토큰을 재사용하세요.

인증 토큰을 획득하기 위해 과도하게 ClientLogin 서비스를 불러오면 '보안문자'에 문제가 발생할 수 있으며 이러한 문제는 사람이 개입하여 해결해야 합니다. 이런 상황을 방지하기 위해 인증 토큰을 여러 요청에 재사용하세요. 토큰의 유효 기간은 2주이지만 그 전에 계정의 비밀번호가 변경되면 기간이 만료됩니다. 기간이 만료된 토큰으로 진행된 요청에는 GOOGLE_ACCOUNT_COOKIE_INVALID 오류가 표시됩니다.

양방향 애플리케이션의 경우에는 시스템에 로그인할 때 인증 토큰을 요청하고 세션 중에 요청을 할 때마다 다시 사용하세요. 자동 애플리케이션의 경우에는 스크립트를 시작할 때 인증 토큰을 요청하고 실행 중에 요청을 할 때마다 다시 사용하세요. 실행 중에 인증 토큰을 보관하면 반복 작업이 쉬워집니다. 단, 보안에 유의하여 토큰을 저장하세요.

2단계 인증 사용 시 애플리케이션 비밀번호의 누락 여부를 확인하세요.

Google은 Google 계정의 보안을 강화하기 위해 사용자의 사전 동의를 얻어 2단계 인증 절차를 적용하고 있습니다. 2단계 인증 절차 사용자가 일반 비밀번호로 계정에 로그인을 시도하면 애플리케이션 전용 비밀번호를 사용해야 한다는 내용의 오류가 ClientLogin API에 표시됩니다. 이 때, 별도의 필드에서 오류의 원인이 잘못된 인증 정보가 아니라 2단계 인증 코드 누락이라는 것을 확인할 수 있습니다.

Error=BadAuthentication
Info=InvalidSecondFactor

이 인터페이스에 접근하는 API에는 반드시 일반 비밀번호 대신 별도의 애플리케이션 전용 비밀번호를 사용하세요. 애플리케이션은 이 같은 오류를 확인하고 사용자가 애플리케이션 전용 비밀번호를 사용하도록 알려 줍니다. 애플리케이션의 2단계 인증 오류를 검사하려면 다음 계정을 이용하세요.

LoginEmail = "2steptester@gmail.com"
Password = "testaccount"

여러 작업을 함께 묶어서 요청 횟수를 줄이세요.

API에 요청을 하면 네트워크 전송, 직렬화, 역직렬화, 백엔드 시스템 호출 등 일정한 고정 비용이 발생합니다. 한 번 요청할 때 여러 작업을 함께 묶어 분류하면 고정 비용은 줄어들고 전체 작업량은 늘어납니다. API에서 mutate() 방식은 다수의 작업을 수용하도록 설계되었으므로 가능하면 단일 작업은 요청하지 마세요.

여러 광고그룹이 포함된 캠페인 하나에 5,000개의 키워드를 추가하는 상황을 예로 들어보겠습니다. 한 개의 키워드마다 한 번씩 요청해 총 5,000번을 요청하는 대신에 500개의 키워드로 요청을 10번 하는 것입니다. 요청이 가능한 작업의 개수는 제한되어 있습니다. 작업을 최적화하려면 배치 크기를 조절하세요.

작업을 타겟 광고그룹 또는 캠페인별로 나누어 분류하세요.

작업 수량이 같을 때 타겟의 광고그룹 또는 캠페인이 모두 동일한 작업이 광고그룹 또는 캠페인의 타겟이 다른 작업에 비해 진행 속도가 빠릅니다. 동일한 광고그룹 또는 캠페인을 타겟으로 하는 작업을 하나의 그룹으로 만들면 요청할 때 타겟 광고그룹 또는 캠페인의 총 개수가 줄어들게 되고 전체 작업의 성과가 향상됩니다.

또한 동일한 광고그룹 또는 캠페인에 요청을 계속해서 보내면 백엔드 프로세스와 충돌하여 CONCURRENT_MODIFICATION 오류로 이어질 수 있습니다. 동일한 광고그룹 또는 캠페인을 대상으로 하는 모든 작업에 요청을 한 번만 한다면 이 같은 충돌이 일어날 가능성이 줄어들 것입니다.

앞에서 설명한 여러 광고그룹이 포함된 캠페인 하나에 5,000개의 키워드를 추가하는 상황을 다시 예로 들어보겠습니다. 500개의 배치로 작업을 나누기에 앞서 타겟 광고그룹별로 키워드를 구분하세요. 이렇게 하면 타겟 광고그룹이 동일한 키워드는 전부 하나의 요청으로 구분될 가능성이 높아지고 한 번 요청할 때 해당되는 타겟 광고그룹의 총 개수는 줄어듭니다. 보다 정교하게 그룹을 나누면 큰 배치는 계속 유지하면서 작업을 확실하게 구분할 수 있습니다.

업데이트를 위해서는 스파스 객체를 보내세요.

애드워즈 API에 객체를 전송할 때는 모든 필드를 역직렬화하고 확인하고 데이터베이스에 저장하세요. 필드의 일부를 업데이트하려고 객체 전체를 전달하면 진행 시간이 길어지고 작업 성과가 떨어질 수 있습니다. 애드워즈 API는 스파스 업데이트 기능을 지원하여 객체에서 변경하기를 원하는 필드나 변경이 필요한 필드에만 입력값을 넣을 수 있습니다. 요청 작업량이 늘어날 수 있으므로 입력값이 채워지지 않았거나 입력값이 없는 필드는 변경하지 않고 그대로 둡니다.

키워드 수준의 입찰가를 업데이트하는 애플리케이션이 스파스 업데이트를 사용하면 요청할 때 광고그룹 ID, 기준 ID, 입찰가 필드에만 입력값을 채우기 때문에 이득이 됩니다. 키워드 150개를 대상으로 검사했을 때, 입력값을 모두 채운 객체를 전달하는 대신 스파스 업데이트를 사용할 경우 효율성이 20% 향상되었습니다.

오류를 처리하고 재시도하세요.

코딩에 주의하고 API를 제대로 이해하면 오류가 발생할 가능성을 현저하게 낮출 수 있습니다. 하지만 수많은 오류들이 불가피하게 발생하며 이러한 오류들은 애플리케이션에서 처리해야 합니다. 가장 일반적인 오류와 대처 요령은 문제해결 가이드에 정리되어 있습니다.

일부 오류는 작업을 잠시 중단하거나 재시도하면 해결됩니다. 이것은 대체로 CONCURRENT_MODIFICATION 또는 UNEXPECTED_INTERNAL_API_ERROR 경우에 해당되지만 작업 중에는 더욱 복잡한 오류 원인이 발생할 수 있습니다. 애플리케이션 작업을 재시도하면 이처럼 일시적 장애를 처리하기에 더욱 용이하고 안정적인 플랫폼이 구축됩니다.

예상치 못한 유형의 오류가 발생했을 때는 반드시 요청 ID와 오류의 세부사항을 기록하세요. 또한 SOAP XML 요청 및 응답을 기록하면 문제를 복제하고 디버깅하는 데 도움이 될 것입니다. 클라이언트 라이브러리requestId 헤더를 검색하는 기능뿐만 아니라 SOAP 요청 및 로깅 기능을 제공합니다.

개발을 위해서 테스트 계정을 사용하세요.

테스트 계정을 사용하면 작업 비용을 들이지 않거나 광고 게재에 영향을 주지 않고 API 호출을 할 수 있습니다. 테스트 계정에 액세스할 때 승인된 개발자 토큰은 필요하지 않으므로 애플리케이션이 검토되기 전에 애드워즈 API를 사용하여 개발을 시작할 수 있습니다. 테스트 계정 및 테스트 계정을 받는 방법에 대해 자세히 알아보려면 애드워즈 테스트 계정 사용하기를 참조하세요.

SOAP 메시지를 압축 파일로 만드세요.

애드워즈 API는 요청이나 응답이 이루어지면 gzip으로 압축된 SOAP 메시지를 제공합니다. 응답이 이루어졌을 때 gzip 압축을 활성화하기 위해 다음 두 HTTP 헤더를 포함합니다.

  • User-Agent: 'gzip' 문자열 포함
  • Accept-Encoding: gzip 값을 가짐

예시:

User-Agent: my program (gzip)
Accept-Encoding: gzip

부분 실패 기능을 활용하세요.

애드워즈 API 요청의 대부분은 성공 아니면 실패의 두 가지 경우만 있습니다. 모두 성공하거나, 아니면 모두 실패하는 것입니다. 작업 중 단 하나의 오류만 있어도 실패할 수 있습니다. 그런데 어떤 경우에는 변경사항들이 서로 무관하고 또 실패한 부분만 검토해야 할 필요가 있을 수도 있습니다. 그런 경우에 부분 실패 기능을 활용하세요.

성공적인 변경사항은 모두 시행하면서 'partialFailure' 헤더를 true로 설정하여 실패 목록을 표시하도록 API에 요청하세요. 모든 공식 클라이언트 라이브러리는 이 플래그를 지원합니다.

타겟팅 아이디어

'STATS' 요청에서는 키워드를 묶어 요청하세요.

새로운 키워드 아이디어를 생성하는 'IDEAS' 요청과는 달리 'STATS' 요청은 이미 존재하는 키워드의 통계를 가져오기 위해 사용합니다. 하나의 TargetingIdeaRelatedToQuerySearchParameter의 모든 키워드에 표시되며 여러 키워드의 데이터를 한 번의 요청으로 가져올 수 있습니다. 예를 들면 키워드 100개의 통계를 가져오는 경우에 각 키워드마다 한 번씩 100번의 요청을 하는 것보다는 100개의 키워드 전체를 한 번에 요청하는 것이 더 효율적입니다.

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

도움이 필요하시나요? 지원 페이지를 방문하세요.