Zuordnungen zur Aufwärtskompatibilität

Mit dem Feld forwardCompatibilityMap erhalten Sie Zugriff auf neueste Funktionen, die in der API noch nicht offiziell verfügbar gemacht wurden. Dieses Feld ist in einigen wichtigen API-Elementen (z. B. Campaign) enthalten.

forwardCompatibilityMap ist vom Typ String_StringMapEntry und stellt eine Zuordnung zwischen Strings dar. Sie dient zum Abrufen und Festlegen der Properties von API-Elementen, d. h. von Properties, die noch nicht als offizielle Attribute des Objekts oder seiner untergeordneten Elemente verfügbar sind. Diese Properties werden über Schlüssel in der forwardCompatibilityMap verfügbar gemacht. Zu den Objekten, die das Feld forwardCompatibilityMap enthalten, gehören Campaign, AdGroup und AdGroupAd.

Zuordnung lesen

Sie müssen in Ihrem Selector.fields-Array nicht auf ein forwardCompatibilityMap-Feld verweisen. Wenn in der API-Version und im verwendeten Dienst mindestens ein Schlüssel verfügbar gemacht wird, ist das Feld forwardCompatibilityMap immer in der Antwort enthalten.

Eine Zuordnung kann eine Reihe von Schlüsseln enthalten (einer pro Objekttyp), die als Erweiterung der offiziellen Attribute des Objekts oder eines seiner untergeordneten Elemente verfügbar gemacht werden. Ein Schlüssel in der forwardCompatibilityMap eines Objekts kann auf ein Attribut eines untergeordneten Elements des Objekts statt auf das Objekt selbst verweisen. So kann beispielsweise der Schlüssel Ad.devicePreferred in der Zuordnung für AdGroupAd auftauchen, doch gehört der Schlüssel in Wirklichkeit zum Ad-Objekt (ein untergeordnetes Element von AdGroupAd).

Zuordnungswerte sind vom Typ string. Abhängig vom zugeordneten Schlüssel und dem Attribut, das er darstellt, können diese Werte jedoch String-Darstellungen von anderen einfachen Datentypen wie etwa ganzen Zahlen oder booleschen Ausdrücken sein. Unter Umständen müssen Sie den Typ umwandeln, bevor Sie den Wert verwenden.

Beispiel für Get-Methode

In diesem Beispiel wird die Methode get() in CampaignService aufgerufen, um den Wert eines bestimmten Schlüssels aus der forwardCompatibilityMap jeder Kampagne zu erhalten.

Java

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

// Create selector.
// Notice there is no need to explicitly request the
// forwardCompatibilityMap, indeed adding to the list of fields
// will throw an error.
SelectorBuilder selectorBuilder =
    new SelectorBuilder().fields(CampaignField.Id).limit(PAGE_SIZE);

int offset = 0;

CampaignPage page;
Map<Long, Boolean> campaignMap = new HashMap<>();
do {
  page = campaignService.get(selectorBuilder.build());

  // Collect the campaigns from the page.
  for (Campaign campaign : page.getEntries()) {
    Map<String, String> forwardCompatibilityMap =
        Maps.toMap(campaign.getForwardCompatibilityMap());
    String value = forwardCompatibilityMap.get(compatibilityMapKey);
    System.out.printf(
        "Campaign ID %d has forward compatibility map value of '%s' for key '%s'.%n",
        campaign.getId(), value, compatibilityMapKey);
    // This demonstrates how to handle a forward compatibility map key where
    // the value is a boolean. Check the forward compatibility map documentation
    // for the data type for each supported key:
    // https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
    campaignMap.put(campaign.getId(), value == null ? null : Boolean.valueOf(value));
  }
  offset += PAGE_SIZE;
  selectorBuilder.increaseOffsetBy(PAGE_SIZE);
} while (offset < page.getTotalNumEntries());
return campaignMap;

C#

// Get the CampaignService.
CampaignService campaignService = (CampaignService)user.GetService(
    AdWordsService.v201802.CampaignService);

// Create selector. There is no need to explicitly request the forwardCompatibilityMap field.
// Requesting this field through selectors will throw an error.
Selector selector = new Selector() {
  fields = new string[] { Campaign.Fields.Id },
  paging = Paging.Default
};

CampaignPage page = new CampaignPage();
Dictionary<long, bool> campaignMap = new Dictionary<long, bool>();

try {
  do {
    // Get the campaigns.
    page = campaignService.get(selector);

    // Display the results.
    if (page != null && page.entries != null) {
      foreach (Campaign campaign in page.entries) {
        Dictionary<String, String> forwardCompatibilityMap =
            campaign.forwardCompatibilityMap.ToDict();

        String value = CollectionUtilities.TryGetValue(
            forwardCompatibilityMap, compatibilityMapKey);

        if (value != null) {
          Console.WriteLine("Campaign ID {0} has forward compatibility map value of " +
              "'{1}' for key '{2}'.", campaign.id, compatibilityMapKey);
          // This demonstrates how to handle a forward compatibility map key where
          // the value is a boolean. Check the forward compatibility map documentation
          // for the data type for each supported key:
          // https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
          campaignMap[campaign.id] = Convert.ToBoolean(value);
        } else {
          campaignMap[campaign.id] = false;
        }
      }
    }
    selector.paging.IncreaseOffset();
  } while (selector.paging.startIndex < page.totalNumEntries);
  Console.WriteLine("Number of campaigns found: {0}", page.totalNumEntries);
} catch (Exception e) {
  throw new System.ApplicationException("Failed to retrieve forward compatibility map for " +
      "campaigns", e);
}
return campaignMap;

PHP

// Get the CampaignService.
$campaignService =
    $adWordsServices->get($session, CampaignService::class);

// Create selector.
// Notice there is no need to explicitly request the
// forwardCompatibilityMap, indeed adding to the list of fields
// will throw an error.
$selector = new Selector();
$selector->setFields(['Id']);
$selector->setPaging(new Paging(0, self::PAGE_LIMIT));

$campaignMap = [];
$foundResults = false;
do {
    // Retrieve campaigns one page at a time, continuing to request pages
    // until all campaigns have been retrieved.
    $page = $campaignService->get($selector);

    // Print out some information for each campaign.
    if ($page->getEntries() !== null) {
        $totalNumEntries = $page->getTotalNumEntries();
        foreach ($page->getEntries() as $campaign) {
            if (is_null($campaign->getForwardCompatibilityMap())) {
                continue;
            }
            $forwardCompatibilityMap = MapEntries::toAssociativeArray(
                $campaign->getForwardCompatibilityMap()
            );
            // This demonstrates how to handle a forward compatibility map key
            // where the value is a boolean. Check the forward compatibility map
            // documentation for the data type for each supported key:
            // https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
            $value =
                boolval($forwardCompatibilityMap[$compatibilityMapKey]);
            $foundResults = true;
            printf(
                "Campaign ID %d has forward compatibility map value of '%s' for "
                . "key '%s'.\n",
                $campaign->getId(),
                $value,
                $compatibilityMapKey
            );
            // Cast the ID to string to prevent 32-bit PHP to convert this to
            // negative number.
            $campaignId = strval($campaign->getId());
            $campaignMap[$campaignId] = $value;
        }
    }
    $selector->getPaging()->setStartIndex(
        $selector->getPaging()->getStartIndex() + self::PAGE_LIMIT
    );
} while ($selector->getPaging()->getStartIndex() < $totalNumEntries);
if (!$foundResults) {
    print "No forward compatibility maps are found.\n";
}

return $campaignMap;

Python

# Get the CampaignService.
campaign_service = client.GetService('CampaignService', version='v201802')

# Create selector.
# Notice there is no need to explicitly request the forwardCompatibilityMap;
# adding to the list of fields will throw an error.
offset = 0
selector = {
    'fields': ['Id'],
    'paging': {
        'startIndex': offset,
        'numberResults': PAGE_SIZE
    }
}

campaign_map = {}
more_pages = True

while more_pages:
  page = campaign_service.get(selector)

  if 'entries' in page:
    for campaign in page['entries']:
      raw_fcm = getattr(
          campaign, 'forwardCompatibilityMap', {})
      forward_compatibility_map = {
          string_map_entry['key']: string_map_entry['value']
          for string_map_entry in raw_fcm
      }

      campaign_id = campaign['id']
      value = forward_compatibility_map.get(bool(compatibility_map_key),
                                            False)
      campaign_map[campaign_id] = value

      # This demonstrates how to handle a forward compatibility map key where
      # the value is a boolean. Check the forward compatibility map
      # documentation for the data type for each supported key:
      # https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
      print ('Campaign with id "%s" has forward compatibility map value of '
             '"%s" for key "%s".' % (campaign_id, value,
                                     compatibility_map_key))
  offset += PAGE_SIZE
  selector['paging']['startIndex'] = offset
  more_pages = offset < int(page['totalNumEntries'])

return campaign_map

Perl

# Create selector.
# Notice there is no need to explicitly request the forwardCompatibilityMap,
# indeed adding to the list of fields will throw an error.
my $paging = Google::Ads::AdWords::v201802::Paging->new({
  startIndex    => 0,
  numberResults => PAGE_SIZE
});
my $selector = Google::Ads::AdWords::v201802::Selector->new({
  fields     => ["Id"],
  paging     => $paging
});

my $campaign_map = {};
# Retrieve campaigns one page at a time, continuing to request pages until
# all campaigns have been retrieved.
Google::Ads::AdWords::Utilities::PageProcessor->new({
    client   => $client,
    service  => $client->CampaignService(),
    selector => $selector
  }
  )->process_entries(
  sub {
    # Print out some information for each campaign.
    my ($campaign) = @_;

    my $forward_compatibility_map =
        Google::Ads::Common::MapUtils::get_map(
          $campaign->get_forwardCompatibilityMap());
    if (defined $forward_compatibility_map) {
      # This demonstrates how to handle a forward compatibility map key
      # where the value is a boolean. Check the forward compatibility map
      # documentation for the data type for each supported key:
      # https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
      my $value = $forward_compatibility_map->{$compatibility_map_key};
      if (defined $value) {
        printf "Campaign ID %d has forward compatibility map value of '%s'" .
          " for key '%s'.\n", $campaign->get_id(), $value,
          $compatibility_map_key;
        $campaign_map->{$campaign->get_id()} = $value;
      }
    }
  });

if (!keys %{$campaign_map}) {
  print "No forward compatibility maps were found.\n";
}

return $campaign_map;

Ruby

# Create selector.
# Notice there is no need to explicitly request the forwardCompatibilityMap,
# indeed adding it to the list of fields will throw an error.
selector = {
  :fields => ['Id'],
  :paging => {
    :start_index => 0,
    :number_results => PAGE_SIZE
  }
}

campaign_map = {}

# Iterate over all pages.
offset, page = 0, {}
begin
  page = campaign_srv.get(selector)
  if page[:entries]
    page[:entries].each do |campaign|
      unless campaign[:forward_compatibility_map].nil?
        value = campaign[:forward_compatibility_map][fcm_key]
        unless value.nil?
          puts ("Campaign ID %d has forward compatibility map value of '%s'" +
             " for key '%s'") % [campaign[:id], fcm_key, value]
          # This demonstrates how to handle a forward compatibility map key
          # where the value is a boolean. Check the forward compatibility map
          # documentation for the data type for each supported key:
          # https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
          campaign_map[campaign[:id]] = (value.casecmp('true') >= 0)
        end
      end
    end
    # Increment values to request the next page.
    offset += PAGE_SIZE
    selector[:paging][:start_index] = offset
  end
end while page[:total_num_entries] > offset

return campaign_map

Properties über die Zuordnung ändern

Schlüssel lassen sich über die forwardCompatibilityMap genau wie jedes andere Attribut verändern: Sie rufen einfach die mutate()-Methode auf und füllen dabei die forwardCompatibilityMap mit den Schlüsseln und Werten, die Sie ändern möchten. Die normalen mutate-Vorgänge ADD und SET akzeptieren forwardCompatibilityMap-Daten. Möglicherweise sind jedoch einige Vorbereitungen erforderlich.

Sie müssen einen gültigen Wert für einen Schlüssel übergeben, da sonst ein ApiException-Fehler auftritt. Außerdem muss der Schlüsselname korrekt sein, da die API bei Verwendung eines falschen oder nicht definierten Namens keine Meldung ausgibt. Dies kann möglicherweise zu schwer zu diagnostizierenden Fehlern führen.

Beispiel für Mutate-Methode

Im folgenden Beispiel wird gezeigt, wie Sie eine Kampagne ändern, indem Sie den Schlüssel und den Wert in der forwardCompatibilityMap senden.

Java

// This is an example on how to update 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 forward compatibility map entry to "true" to update the campaign.
// This demonstrates how to handle a forward compatibility map key where
// the value is a boolean. Check the forward compatibility map documentation
// for the data type for each supported key:
// https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
campaign.setForwardCompatibilityMap(
    new String_StringMapEntry[] {
      new String_StringMapEntry(compatibilityMapKey, 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);
System.out.printf(
    "Updated forward compatibility map of campaign ID %d.%n", result.getValue(0).getId());

C#

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

// Get the CampaignService.
CampaignService campaignService = (CampaignService)user.GetService(
    AdWordsService.v201802.CampaignService);

// Create campaign with updated status.
Campaign campaign = new Campaign();
campaign.id = campaignId;
// Set the forward compatibility map entry to "true" to update the campaign.
// This demonstrates how to handle a forward compatibility map key where
// the value is a boolean. Check the forward compatibility map documentation
// for the data type for each supported key:
// https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
campaign.forwardCompatibilityMap = new String_StringMapEntry[] {
  new String_StringMapEntry() {
    key = compatibilityMapKey,
    value = Boolean.TrueString
  }
};

// Create operations.
CampaignOperation operation = new CampaignOperation();
operation.operand = campaign;
operation.@operator = Operator.SET;

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

  // Update campaign.
  CampaignReturnValue result = campaignService.mutate(operations);
  Console.WriteLine("Updated forward compatibility map of campaign ID {0}.",
      result.value[0].id);
} catch (Exception e) {
  throw new System.ApplicationException("Failed to update forward compatibility map for " +
      "campaigns", e);
}

PHP

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

// Get the CampaignService.
$campaignService =
    $adWordsServices->get($session, CampaignService::class);

// Create campaign with updated status.
$campaign = new Campaign();
$campaign->setId($campaignId);
// Set the forward compatibility map entry to "true" to update the campaign.
// This demonstrates how to handle a forward compatibility map key
// where the value is a boolean. Check the forward compatibility map
// documentation for the data type for each supported key:
// https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
$campaign->setForwardCompatibilityMap(
    [
        new String_StringMapEntry($compatibilityMapKey, 'true')
    ]
);

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

// Update campaign on the server.
$result = $campaignService->mutate([$operation]);
printf(
    "Updated forward compatibility map of campaign ID %d.\n",
    $result->getValue()[0]->getId()
);

Python

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

# Get the CampaignService.
campaign_service = client.GetService('CampaignService', version='v201802')

# Create campaign with updated status.
campaign = {
    'id': campaign_id,
    # This demonstrates how to handle a forward compatibility map key where
    # the value is a boolean. Check the forward compatibility map
    # documentation for the data type for each supported key:
    # https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
    'forwardCompatibilityMap': [{
        'key': compatibility_map_key,
        'value': str(True)
    }]
}

# Create operations.
operations = [{
    'operand': campaign,
    'operator': 'SET'
}]

# Update campaign.
updated_campaign = campaign_service.mutate(operations)['value'][0]
print 'Updated forward compatibility map of campaign ID "%d".' % (
    updated_campaign['id'])

Perl

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

# Create campaign with updated status.
my $campaign = Google::Ads::AdWords::v201802::Campaign->new({
  id => $campaign_id,
  # Set the forward compatibility map entry to "1" to update the campaign.
  # This demonstrates how to handle a forward compatibility map key
  # where the value is a boolean. Check the forward compatibility map
  # documentation for the data type for each supported key:
  # https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
  forwardCompatibilityMap =>
    [Google::Ads::AdWords::v201802::String_StringMapEntry->new({
      key   => $compatibility_map_key,
      value => 1})]
});

my $operation = Google::Ads::AdWords::v201802::CampaignOperation->new({
  operand  => $campaign,
  operator => "SET"
});

# Update campaign on the server.
my $result = $client->CampaignService()->mutate({
  operations => [$operation]});

printf("Updated forward compatibility map of campaign ID %d.\n",
      $result->get_value()->[0]->get_id());

Ruby

# Prepare for updating campaign.
operation = {
  :operator => 'SET',
  :operand => {
    :id => campaign_id,
    # Set the forward compatibility map entry to "true" as an example.
    :forward_compatibility_map => [
      {:key => fcm_key, :value => true}
    ]
  }
}

# Update campaign.
response = campaign_srv.mutate([operation])
if response and response[:value]
  campaign = response[:value].first
  puts "Campaign ID %d was successfully updated." % campaign[:id]
else
  puts 'No campaigns were updated.'
end

Umgang mit Fehlern

Bestimmte Vorgänge wie das Übergeben eines ungültigen Werts für einen Schlüssel in der forwardCompatibilityMap verursachen eine ApiException mit einem ApiError. Dieser Fehler enthält den fieldPath zur forwardCompatibilityMap und einen trigger, in dem der ungültige Wert angegeben ist.

Das Übergeben eines ungültigen Schlüsselnamens kann zu Fehlern führen, die schwer zu diagnostizieren sind, da die API bei ungültigen Namen keine Fehlermeldung ausgibt.

Schlüssel sind an bestimmte API-Versionen gebunden. Ein Schlüssel, der für eine bestimmte Version gültig ist, wird in einer zukünftigen Version nicht mehr akzeptiert, wenn seine Funktionalität bereits offiziell in der API implementiert wurde. Wenn ein Schlüssel an eine API-Version übergeben wird, die den Schlüssel nicht mehr akzeptiert, wird ein ApiException-Fehler zurückgegeben.

Häufig gestellte Fragen

Wie fordere ich das Auffüllen der forwardCompatibilityMap in einer Antwort an? Ich finde in der Dokumentation keinen entsprechenden Feldnamen.

Eine explizite Anfrage in Selector.fields ist nicht erforderlich. Die Zuordnung wird aufgefüllt, wenn Daten an das Objekt angefügt sind, die in der Zuordnung zurückgegeben werden sollen.

Warum wird die forwardCompatibilityMap nicht aufgefüllt?

Im Allgemeinen liegt das daran, dass für das Objekt keine Daten an den entsprechenden Schlüssel angefügt wurden.

Erhalte ich eine Fehlermeldung, wenn ich in der Zuordnung den falschen Schlüssel sende?

Nein. Geben Sie unbedingt den richtigen Schlüsselnamen an, da die API bei nicht erkannten Schlüsseln keine Fehlermeldung ausgibt.

Ich weiß, dass in einem Objekt ein neues Feld bzw. ein neuer Schlüssel unterstützt wird, das Objekt enthält aber keine forwardCompatibilityMap.

Nur API-Elemente der obersten Ebene, z. B. Campaign, AdGroup und AdGroupAd, machen die forwardCompatibilityMap verfügbar. Bestimmte Schlüssel beziehen sich jedoch auf untergeordnete Objekte.

Was geschieht, wenn ich in der Zuordnung einen falschen Wert sende?

Wenn Sie den richtigen Schlüssel angeben, aber einen nicht unterstützten Wert verwenden, wird eine ApiException zurückgegeben.

Werden Schlüssel in allen API-Versionen verfügbar gemacht?

Nein. Schlüssel werden nur in API-Versionen verfügbar gemacht bzw. akzeptiert, in denen die entsprechende Funktionalität noch nicht offiziell verfügbar gemacht wurde.

Aktuelle forwardCompatibilityMap-Schlüssel

Verfügbare forwardCompatibilityMap-Schlüssel
Dienst
AdGroupAdService
Entität
AdGroupAd
Schlüsselname
Ad.type
Auswahlfeld
AdType
Typ
Enum
Unterstützte Version
Version 201710 und Version 201802
Schreibgeschützt

Legen Sie dies auf AD_VARIATION fest, wenn eine ExpandedTextAd eine Anzeigenvariation ist. Bei allen anderen Arten von Anzeigen sowie bei ExpandedTextAd-Anzeigen, die keine Anzeigenvariationen sind, ist dieser Schlüssel nicht in der forwardCompatibilityMap.

Anzeigenvariationen können seit v201802 erkannt werden. Verwenden Sie dieses Feld, wenn Sie sie in früheren API-Versionen ermitteln möchten.

Feedback geben zu...