Zuordnungen zur Aufwärtskompatibilität

Mit dem Feld forwardCompatibilityMap erhalten Sie Zugriff auf aktuelle neue Funktionen, die in der API noch nicht offiziell verfügbar gemacht wurden. Dieses Feld ist in bestimmten zentralen 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

Im folgenden Beispiel erfolgt ein Aufruf der Methode get() in CampaignService, um den Schlüssel Campaign.enhanced aus seiner forwardCompatibilityMap abzurufen. Dieses Beispiel stammt aus unserer Java-Clientbibliothek.

 // 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.");
 }

Properties über die Zuordnung ändern

Das Ändern von Schlüsseln, z. B. des Schlüssels Campaign.enhanced, mithilfe von forwardCompatibilityMap erfolgt auf die gleiche Weise wie bei jedem anderen Attribut. Sie müssen lediglich die mutate()-Methode aufrufen und forwardCompatibilityMap mit den Schlüsseln und Werten auffüllen, die geändert werden sollen. 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. Stellen Sie außerdem sicher, dass der Schlüsselname korrekt ist, da die API bei Verwendung eines falschen bzw. nicht definierten Schlüsselnamens keine Meldung ausgibt und dadurch möglicherweise schwer zu diagnostizierende Fehler verursacht werden.

Beispiel für mutateMil

Im folgenden Beispiel wird gezeigt, wie Sie eine Kampagne in eine erweiterte Kampagne ändern, indem Sie den Schlüssel Campaign.enhanced mit dem Wert true in der forwardCompatibilityMap senden. Dieses Beispiel stammt aus der Java-Clientbibliothek.

// 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);

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 wurden, 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.

Feedback geben zu...