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, einschließlich mehrerer sequenzieller 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 eine gesamte BatchJob für alle zugehörigen AddBatchJobOperations-Uploads.

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, ausgenommen 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, geben Sie customers/CUSTOMER_ID/campaigns/-1 als übergeordnete Kampagne an. Die API ersetzt -1 automatisch durch die tatsächliche Kampagnen-ID, die beim Erstellen generiert wird.

Nutzungsbeschränkungen

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

• Reihenfolge beachten: Sie können auf einen temporären Ressourcennamen erst 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 erscheinen, mit dem die übergeordnete Ressource erstellt wird (z. B. das Erstellen einer Kampagne).
• Bereich für einzelne Anfragen oder Batchjobs: Temporäre Ressourcennamen bleiben nicht über separate Jobs oder Mutationsanfragen hinweg erhalten. Wenn Sie auf eine Ressource verweisen möchten, die in einem vorherigen Job oder einer Mutationsanfrage erstellt wurde, verwenden Sie den tatsächlichen, vom System generierten Ressourcennamen.
• Globale Eindeutigkeit: Innerhalb eines einzelnen Jobs oder einer Mutationsanfrage muss jeder temporäre Ressourcenname eine eindeutige negative Ganzzahl für alle Ressourcentypen verwenden. Sie können beispielsweise -1 nicht in derselben Anfrage sowohl einer Kampagne als auch einer Anzeigengruppe 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 eine Kampagne, eine Anzeigengruppe und eine Anzeige in einer einzigen API-Anfrage oder einem einzigen Batchauftrag hinzufügen. Sie können das mutateOperations-Array in einer GoogleAdsService.Mutate- oder BatchJobService.AddBatchJobOperations-Anfragenutzlast strukturieren, wie im folgenden REST-JSON-Beispiel gezeigt (andere erforderliche Ressourcenfelder wurden der Einfachheit 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"
        }
      }
    }
  ]
}

In diesem Beispiel werden die folgenden wichtigen Details veranschaulicht:

• 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 im vorherigen Vorgang erstellten Kampagne zu verknüpfen.
• adGroupAdOperation verweist auf customers/CUSTOMER_ID/adGroups/-2 und lässt resourceName aus, da kein nachfolgender Vorgang in der Anfrage auf die neue Anzeige verweist.

Fehlerbehandlung in Batchjobs

Da Standardvorgänge in einem Batchjob mit aktiviertem teilweisen Fehler ausgeführt werden (außer innerhalb von atomaren Unterbatches), schlagen alle abhängigen untergeordneten Vorgänge, die auf diese temporäre ID verweisen, mit NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS fehl, wenn eine übergeordnete Ressource mit einer temporären ID die Validierung nicht besteht. Wenn Sie dieselbe negative ID für mehrere create-Vorgänge innerhalb desselben 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.