Temporäre IDs verwenden

Temporäre Ressourcennamen

BatchJobService unterstützt temporäre Ressourcennamen, auf die in nachfolgenden Vorgängen innerhalb desselben Batchjobs verwiesen werden kann. Das gilt auch für mehrere sequenzielle AddBatchJobOperations -Anfragen, die mit einem sequence_token hochgeladen wurden. So können Sie eine Kampagne und die zugehörigen Anzeigengruppen, Anzeigen und Kriterien in einem einzigen Batchjob erstellen, bevor serverseitige IDs zugewiesen werden. In den folgenden allgemeinen Regeln und im Beispiel bezieht sich eine einzelne Anfrage auf einen gesamten BatchJob über alle AddBatchJobOperations-Uploads hinweg.

Wenn Sie in derselben Mutationsanfrage oder demselben Batchjob auf eine neu erstellte Ressource verweisen möchten, geben Sie im Feld resource_name der neuen Ressource eine negative Ganzzahl-ID an (z. B. -1 oder -2, aber nicht 0). Wenn Sie beispielsweise eine Kampagne in einer Batchanfrage erstellen, legen Sie den Ressourcennamen auf customers/CUSTOMER_ID/campaigns/-1 fest. Wenn Sie in einem späteren Vorgang innerhalb derselben Anfrage eine Anzeigengruppe erstellen, verweisen Sie auf customers/CUSTOMER_ID/campaigns/-1 als übergeordnete Kampagne. Die API ersetzt -1 automatisch durch die tatsächliche Kampagnen-ID, die bei der Erstellung generiert wurde.

Nutzungsbeschränkungen

Beachten Sie bei der Verwendung temporärer Ressourcennamen die folgenden Regeln:

• Reihenfolge ist wichtig:Sie können nur auf einen temporären Ressourcennamen verweisen, nachdem Sie ihn definiert haben. In einer Liste von Vorgängen muss der abhängige Vorgang (z. B. das Erstellen einer Anzeigengruppe) nach dem Vorgang stehen, mit dem die übergeordnete Ressource erstellt wird (z. B. das Erstellen einer Kampagne).
• Geltungsbereich: Einzelne Anfrage oder Batchjob : Temporäre Ressourcennamen bleiben nicht über separate Jobs oder Änderungsanfragen hinweg bestehen. Wenn Sie auf eine Ressource verweisen möchten, die in einem vorherigen Job oder einer vorherigen Mutationsanfrage erstellt wurde, verwenden Sie den tatsächlichen vom System generierten Ressourcennamen.
• Globale Eindeutigkeit:Innerhalb eines einzelnen Jobs oder einer einzelnen Mutationsanfrage muss für jeden temporären Ressourcennamen eine eindeutige negative Ganzzahl für alle Ressourcentypen verwendet werden. Sie können beispielsweise nicht in derselben Anfrage sowohl einer Kampagne als auch einer Anzeigengruppe -1 zuweisen. Wenn Sie eine temporäre ID innerhalb derselben Anfrage oder desselben Batchjobs wiederverwenden, wird der Fehler NewResourceCreationError.DUPLICATE_TEMP_IDS zurückgegeben.

Beispielnutzlast

Angenommen, Sie möchten in einer einzigen API-Anfrage oder einem einzigen Batchjob eine Kampagne, eine Anzeigengruppe und eine Anzeige hinzufügen. Sie können das Array mutateOperations in einer GoogleAdsService.Mutate- oder BatchJobService.AddBatchJobOperations-Anfrage wie im folgenden REST-JSON-Beispiel strukturieren. Andere erforderliche Ressourcenfelder wurden der Kürze halber weggelassen:

{
  "mutateOperations": [
    {
      "campaignOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/adGroups/-2",
          "campaign": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupAdOperation": {
        "create": {
          "adGroup": "customers/CUSTOMER_ID/adGroups/-2"
        }
      }
    }
  ]
}

Dieses Beispiel veranschaulicht die folgenden wichtigen Details:

• Die Anzeigengruppe verwendet eine neue temporäre ID (-2), da -1 bereits der Kampagne zugewiesen ist.
• Die Anzeigengruppe verweist auf customers/CUSTOMER_ID/campaigns/-1, um sich mit der Kampagne zu verknüpfen, die im vorherigen Vorgang erstellt wurde.
• Der Vorgang adGroupAdOperation verweist auf customers/CUSTOMER_ID/adGroups/-2 und lässt resourceName weg, da in keinem nachfolgenden Vorgang in der Anfrage auf die neue Anzeige verwiesen wird.

Fehlerbehandlung in Batchjobs

Da Standardvorgänge in einem Batchjob mit aktivierter teilweiser Fehlerbehebung ausgeführt werden (außer in atomaren Unter-Batches), schlagen alle abhängigen untergeordneten Vorgänge, die auf eine temporäre ID verweisen, mit NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS fehl, wenn die Validierung einer übergeordneten Ressource mit einer temporären ID fehlschlägt. Wenn Sie dieselbe negative ID in mehreren create Vorgängen innerhalb des selben Batchjobs wiederverwenden, wird NewResourceCreationError.DUPLICATE_TEMP_IDS zurückgegeben. Temporäre IDs sind nur beim Erstellen von Ressourcen (create) oder beim Verweisen auf neu erstellte übergeordnete Ressourcen gültig. Wenn Sie beispielsweise eine negative temporäre ID in AdGroupCriterionOperation.remove übergeben, wenn Sie AddBatchJobOperations aufrufen, wird RequestError.RESOURCE_NAME_MALFORMED zurückgegeben.