Method: customers.googleAds.mutate

Erstellt, aktualisiert oder entfernt Ressourcen. Diese Methode unterstützt atomare Transaktionen mit mehreren Arten von Ressourcen. So können Sie beispielsweise eine Kampagne und ein Kampagnenbudget einheitlich erstellen oder bis zu Tausende von Änderungen einheitlich vornehmen.

Diese Methode ist im Grunde ein Wrapper für eine Reihe von Methoden zum Ändern von Daten. Im Vergleich zum direkten Aufruf dieser Methoden bietet sie nur folgende Funktionen:

  • Atomare Transaktionen
  • Namen temporärer Ressourcen (siehe unten)
  • Etwas geringere Latenz bei mehreren Muta-Aufrufen

Hinweis: Es werden nur Ressourcen berücksichtigt, die atomare Transaktionen unterstützen. Daher können mit dieser Methode nicht alle Aufrufe einzelner Dienste ersetzt werden.

Vorteile atomarer Transaktionen

Die Atomarität erleichtert die Fehlerbehandlung erheblich. Wenn Sie mehrere Änderungen vornehmen und eine davon fehlschlägt, kann Ihr Konto in einen inkonsistenten Zustand versetzt werden. Bei der Atomarität wird entweder direkt der gewünschte Status erreicht oder die Anfrage schlägt fehl und Sie können es noch einmal versuchen.

Namen temporärer Ressourcen

Temporäre Ressourcennamen sind eine spezielle Art von Ressourcennamen, mit denen eine Ressource erstellt und in derselben Anfrage darauf verwiesen wird. Wenn beispielsweise ein Kampagnenbudget erstellt wird, bei dem resourceName = customers/123/campaignBudgets/-1 ist, kann dieser Ressourcenname im Feld Campaign.budget in derselben Anfrage wiederverwendet werden. So werden die beiden Ressourcen atomar erstellt und verknüpft.

Wenn Sie einen temporären Ressourcennamen erstellen möchten, geben Sie in den Teil des Namens, der normalerweise vom Server zugewiesen wird, eine negative Zahl ein.

Hinweis:

  • Ressourcen müssen mit einem temporären Namen erstellt werden, bevor der Name wiederverwendet werden kann. Das Beispiel „CampaignBudget+Campaign“ würde beispielsweise fehlschlagen, wenn die Reihenfolge der Mutationen umgekehrt wäre.
  • Temporäre Namen werden nicht für mehrere Anfragen gespeichert.
  • Die Anzahl der temporären Namen in einer Anfrage ist nicht begrenzt.
  • Für jeden temporären Namen muss eine eindeutige negative Zahl verwendet werden, auch wenn sich die Ressourcentypen unterscheiden.

Latenz

Es ist wichtig, Mutationen nach Ressourcentyp zu gruppieren, da die Anfrage sonst möglicherweise wegen Zeitüberschreitung fehlschlägt. Die Latenz entspricht ungefähr einer Reihe von Aufrufen einzelner Mutatmethoden, wobei jede Änderung des Ressourcentyps einen neuen Aufruf darstellt. Wenn Sie beispielsweise 10 Kampagnen und dann 10 Anzeigengruppen mutieren, entspricht das zwei Aufrufen. Wenn Sie dagegen 1 Kampagne, 1 Anzeigengruppe, 1 Kampagne und 1 Anzeigengruppe mutieren, entspricht das vier Aufrufen.

Liste der geworfenen Fehler: AdCustomizerError AdError AdGroupAdError AdGroupCriterionError AdGroupError AssetError AuthenticationError AuthorizationError BiddingError CampaignBudgetError CampaignCriterionError CampaignError CampaignExperimentError CampaignSharedSetError CollectionSizeError ContextError ConversionActionError CriterionError CustomerFeedError DatabaseError DateError DateRangeError DistinctError ExtensionFeedItemError ExtensionSettingError FeedAttributeReferenceError FeedError FeedItemError FeedItemSetError FieldError FieldMaskError FunctionParsingError HeaderError ImageError InternalError KeywordPlanAdGroupKeywordError KeywordPlanCampaignError KeywordPlanError LabelError ListOperationError MediaUploadError MutateError NewResourceCreationError NullError OperationAccessDeniedError PolicyFindingError PolicyViolationError QuotaError RangeError RequestError ResourceCountLimitExceededError SettingError SharedSetError SizeLimitError StringFormatError StringLengthError UrlFieldError

HTTP-Anfrage

POST https://googleads.googleapis.com/v19/customers/{customerId}/googleAds:mutate

Die URL verwendet die Syntax der gRPC-Transcodierung.

Pfadparameter

Parameter
customerId

string

Erforderlich. Die ID des Kunden, dessen Ressourcen geändert werden.

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

JSON-Darstellung 
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
Felder
mutateOperations[]

object (MutateOperation)

Erforderlich. Liste der Vorgänge, die auf einzelnen Ressourcen ausgeführt werden sollen.
partialFailure

boolean

Wenn diese Option aktiviert ist, werden erfolgreiche Vorgänge ausgeführt und ungültige Vorgänge geben Fehler zurück. Wenn „falsch“ festgelegt ist, werden alle Vorgänge nur dann in einer Transaktion ausgeführt, wenn sie alle gültig sind. Der Standardwert ist "false".
validateOnly

boolean

Wenn „true“, wird die Anfrage validiert, aber nicht ausgeführt. Es werden nur Fehler zurückgegeben, keine Ergebnisse.
responseContentType

enum (ResponseContentType)

Die Einstellung für den Antwortinhaltstyp. Bestimmt, ob die veränderliche Ressource oder nur der Ressourcenname nach der Mutation zurückgegeben werden soll. Die änderbare Ressource wird nur zurückgegeben, wenn sie das entsprechende Antwortfeld hat. Beispiel: „MutateCampaignResult.campaign“.

Antworttext

Antwortnachricht für GoogleAdsService.Mutate.

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

JSON-Darstellung 
{
  "partialFailureError": {
    object (Status)
  },
  "mutateOperationResponses": [
    {
      object (MutateOperationResponse)
    }
  ]
}
Felder
partialFailureError

object (Status)

Fehler, die sich auf Betriebsfehler im Modus „Teilweise fehlgeschlagene Vorgänge“ beziehen. Wird nur zurückgegeben, wenn „partialFailure“ = „true“ und alle Fehler innerhalb der Vorgänge auftreten. Wenn Fehler außerhalb der Vorgänge auftreten (z. B. Authentifizierungsfehler), geben wir einen Fehler auf RPC-Ebene zurück.
mutateOperationResponses[]

object (MutateOperationResponse)

Alle Antworten für die Mutation.

Autorisierungsbereiche

Erfordert den folgenden OAuth-Bereich:

  • https://www.googleapis.com/auth/adwords

Weitere Informationen finden Sie unter OAuth 2.0 Overview.