이후 버전과의 호환성 지도의 사용

이 페이지는 애드워즈 API에서 이후 버전과의 호환성 지도의 사용에 대해 설명합니다.

  1. 이후 버전과의 호환성 지도의 이해
  2. 지도 읽기
  3. 지도를 이용하여 속성 변형
  4. 오류 처리
  5. FAQ
  6. 사용 가능한 ForwardCompatibilityMap 키

이후 버전과의 호환성 지도의 이해

forwardCompatibilityMap 필드는 공식적으로 API에 노출되기 전에 최첨단의 기능을 탐색할 수 있도록 도와줍니다. 이 필드는 Campaigns 객체와 같은 일부 주요 AP에 포함됩니다.

forwardCompatibilityMapString_StringMapEntry[] 유형입니다. 이것은 문자열을 문자열로 매핑하는 것을 나타내며 API 항목에 간단한 속성을 얻고 설정하는 데 사용됩니다. 이 속성은 아직 객체 또는 그 후손의 형식적인 속성으로서 사용할 수 없습니다. 이러한 속성은 forwardCompatibilityMap의 키를 통해 노출됩니다. 사용할 수 있는 키의 목록은 이 표를 참조하시기 바랍니다. API의 Campaigns, AdGroups, AdGroupAds 및 기타 여러 객체는 이미 forwardCompatibilityMap 필드를 노출합니다.

이 가이드에서는 이후 버전과의 호환성 지도를 읽고 업데이트하는 방법에 대해 안내해 드립니다.

지도 읽기

이후 버전과의 호환성 지도에서 데이터에 액세스하는 방법은 forwardCompatibilityMap 필드를 Selector.fields 배열의 일부로 참조할 필요가 없다는 점이 다를 뿐, 객체의 다른 필드와 동일합니다. 다시 말해 API 버전 및 사용중인 서비스에 노출된 키가 하나라도 있을 경우 forwardCompatibilityMap 필드가 항상 응답에 표시되게 됩니다.

forwardCompatibilityMap은 객체 또는 이의 후손 중 하나의 형식적 속성의 확장으로서 노출된 각 객체 유형에 따라 다른 키 조합을 포함할 수 있습니다. 객체의 forwardCompatibilityMap 키는 객체 자신보다는 객체 후손의 속성을 참조할 수 있습니다. 예를 들어 Ad.devicePreferred 키는 AdGroupAd의 지도에서 볼 수 있지만 실제로는 AdGroupAd의 후손 중 하나인 Ad 객체에 속합니다.

지도 값은 string 유형이지만 연관된 키 및 표현되는 속성에 따라 이 값은 정수 또는 부울과 같은 기타 기본 데이터 형식의 문자열 표현이 될 수 있습니다. 특정의 경우 클라이언트 측에서 유형 전환이 필요할 수도 있습니다.

다음은 forwardCompatibilityMap에서 Campaign.enhanced 키를 얻기위한 CampaignService에 대한 GET 호출의 예입니다. 이 예는 자바 클라이언트 라이브러리에 기초를 둡니다.

 // Get the CampaignService.
 CampaignServiceInterface campaignService =
     adWordsServices.get(session, CampaignServiceInterface.class);

 // Create selector.
 Selector selector = new Selector();
 // Set the selector fields.
 // Notice there is no need to explicitly request the
 // forwardCompatibilityMap, indeed adding to the list of fields
 // will throw an error.
 selector.setFields(new String[] {"Id", "Name"});

 CampaignPage page = campaignService.get(selector);

 // Display campaigns.
 if (page.getEntries() != null) {
   for (Campaign campaign : page.getEntries()) {
     Map forwardCompatibilityMap =
         Maps.toMap(campaign.getForwardCompatibilityMap());
     System.out.println(String.format(
         "Campaign ID %d has enhanced value of '%s'",
         campaign.getId(),
         forwardCompatibilityMap.get("Campaign.enhanced")));
   }
 } else {
   System.out.println("No campaigns were found.");
 }

지도를 이용하여 속성 변형

이전 예에 표시된 Campaign.enhanced 키와 같이 forwardCompatibilityMap을 통한 변형 키는 다른 속성과 다르지 않습니다. 그러므로 forwardCompatibilityMap이 변경하려는 키 및 값과 함께 게재되도록 일반 mutate 호출을 구성하기만 하면 됩니다. 일반 ADD 및 SET mutate 연산은 아래 표의 참고 항목에 설명된 것과 같은 몇몇 규정을 사용하는 forwardCompatibilityMap 데이터를 허용합니다.

잘못된 을 전달하면 ApiException이 발생하므로 항상 키에 대해 유효한 값이 전달되도록 해야합니다. 또한 잘못되거나 정의되지 않은 키 이름을 사용하면 API는 이에 대해 알리지 않고 무시하므로 디버깅이 어려운 오류를 초래하기 때문에 특히 정확한 키 이름을 사용해야 합니다. 더 자세한 내용은 이 가이드의 오류 처리 섹션을 참조하세요.


다음 예는 forwardCompatibilityMap에서 'true' 값을 사용하는 Campaign.enhanced 키를 전송함으로써 캠페인을 고급 캠페인으로 변경하는 방법을 보여줍니다. 이 예는 자바 클라이언트 라이브러리에 기초를 둡니다.

 // This is an example on how to enhance a campaign using the
 // CampaignService and the forwardCompatibilityMap field.

 // Get the CampaignService.
 CampaignServiceInterface campaignService =
     adWordsServices.get(session, CampaignServiceInterface.class);

 // Create campaign with updated status.
 Campaign campaign = new Campaign();
 campaign.setId(campaignId);
 // Set the "Campaign.enhanced" as "true" to update the campaign.
 campaign.setForwardCompatibilityMap(new String_StringMapEntry[] {
     new String_StringMapEntry("Campaign.enhanced",
         Boolean.TRUE.toString())});

 // Create operations.
 CampaignOperation operation = new CampaignOperation();
 operation.setOperand(campaign);
 operation.setOperator(Operator.SET);

 CampaignOperation[] operations =
     new CampaignOperation[] {operation};

 // Update campaign.
 CampaignReturnValue result = campaignService.mutate(operations);

오류 처리

forwardCompatibilityMap에 유효하지 않은 키의 을 전달하는 등의 특정 작업은 ApiError를 포함한 ApiException 결과를 초래합니다. 이 오류는 forwardCompatibilityMap을 가르키는 fieldPath 및 잘못된 값을 게재하는 trigger를 포함하게 됩니다.

잘못된 키 이름을 전달하면 API는 이를 따로 알리지 않고 허용하므로 오류를 진단하기 어려워집니다.

키는 API 버전에 연결되어 있다는 점도 주의해야 합니다. 특정 버전에 유효한 키는 API에 기능이 공식적으로 구현됨과 동시에 이후 버전에서는 허용이 중지됩니다. 더 이상 허용되지 않는 키가 API에 전달되면 ApiException이 반환됩니다.

FAQ

응답에 forwardCompatibilityMap을 게재되게 하려면 어떻게 해야 하나요? 문서에서 이 필드의 이름을 찾을 수 없습니다.

지도에 반환되어야 하는 객체에 데이터가 첨부된 경우 스스로 게재되게 되므로 Selector.fields의 일부로 이를 요청할 필요가 없습니다.

forwardCompatibilityMap이 게재되지 않는 이유는 무엇인가요?

일반적으로 객체에 지도에서 보고자하는 키에 첨부된 데이터가 없기 때문입니다.

지도에 잘못된 키를 전송하면 오류가 발생하나요?

아니요. 하지만 API는 인식되지 않는 키는 이를 알리지 않고 무시하므로 키의 이름을 지정할 때 주의햐야 합니다.

객체에서 지원되는 새 필드 및 키가 있다고 알고 있습니다. 하지만 forwardCompatibilityMap을 지닌 객체를 찾을 수 없습니다.

Campaign, AdGroup 및 AdGroupAd와 같이 오직 최상위 수준의 API 항목만 forwardCompatibilityMap에 노출됩니다. 그러나 일부 키는 근본 객체에 영향을 미칩니다.

지도에 잘못된 값을 보내면 어떻게 되나요?

올바른 키를 지원되지 않는 값으로 설정하면 ApiException이 반환됩니다.

키는 모든 API 버전에 노출되나요?

아니요. 키는 이미 노출된 기능을 가지고 있지 않은 API 버전에만 노출되고 허용됩니다.

사용 가능한 ForwardCompatibilityMap 키

대상 유형 - 값 지원되는 버전 참고
Campaign.enhanced Campaign 부울 - [true, false] v201302 - v201306

SET은 항상 true여야 하며 true로 설정된 후에는 false로 되돌릴 수 없습니다.

Ad.devicePreference AdGroupAd Id - [30001] v201302

이 키는 광고 자체에 속하고 다른 광고의 속성으로 사용되기 때문에 변경할 수 없습니다. 따라서 mutate ADD 연산에만 허용됩니다.

다음과 같은 광고 유형에만 첨부할 수 있습니다.

  • TextAd,
  • ImageAd,
  • DynamicSearchAd,
  • TemplateAd,
  • RichMediaAd,
  • ThirdPartyRedirectAd

고급 캠페인에 포함된 광고에만 설정될 수 있습니다.

이 값은 HIGH_END_MOBILE 플랫폼을 참조하는 30001로만 설정될 수 있습니다.

이는 애드워즈 UI에서 광고를 모바일에 최적화된 것으로 표시하는 것과 같습니다.

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

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