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, auch über mehrere sequenzielle AddBatchJobOperations-Anfragen hinweg, 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 mit allen 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 (außer 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 beim Erstellen generiert wird.

Nutzungseinschränkungen

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

• Reihenfolge wichtig:Sie können erst 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).
• Bereich für einzelne Anfragen oder Batchjobs:Temporäre Ressourcennamen bleiben nicht über separate Jobs oder Änderungsanfragen hinweg erhalten. 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:In einem einzelnen Job oder einer einzelnen Mutationsanfrage muss für jeden temporären Ressourcennamen eine eindeutige negative Ganzzahl für alle Ressourcentypen verwendet werden. Sie können -1 beispielsweise 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 einzelnen API-Anfrage oder einem Batch-Job hinzufügen. Sie können das mutateOperations-Array in einer GoogleAdsService.Mutate- oder BatchJobService.AddBatchJobOperations-Anfrage-Nutzlast 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.
• Die 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 Batch-Job mit aktivierter Teilfehlerbehandlung ausgeführt werden (außer in atomaren Sub-Batches), schlagen alle abhängigen untergeordneten Vorgänge, die auf diese 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 für mehrere create-Vorgänge im selben Batchjob 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.