Utiliser des ID temporaires

Noms de ressources temporaires

BatchJobService est compatible avec les noms de ressources temporaires qui peuvent être référencés dans des opérations ultérieures au sein du même job par lot, y compris dans plusieurs requêtes AddBatchJobOperations séquentielles importées avec un sequence_token. Cela vous permet de créer une campagne, ainsi que ses groupes d'annonces, annonces et critères dépendants, dans un seul job par lot avant que des ID côté serveur ne soient attribués. Dans les règles générales et l'exemple suivants, une seule requête fait référence à un BatchJob entier dans toutes ses importations AddBatchJobOperations.

Pour référencer une ressource nouvellement créée dans la même requête de mutation ou le même job par lot, spécifiez un ID entier négatif (tel que -1 ou -2, à l'exclusion de 0) dans le champ resource_name de la nouvelle ressource. Par exemple, lorsque vous créez une campagne dans une requête par lot, définissez son nom de ressource sur customers/CUSTOMER_ID/campaigns/-1. Lorsque vous créez un groupe d'annonces dans une opération ultérieure de la même requête, référencez customers/CUSTOMER_ID/campaigns/-1 comme campagne parente. L'API remplace automatiquement -1 par l'ID de campagne réel généré lors de la création.

Contraintes d'utilisation

Tenez compte des règles suivantes lorsque vous utilisez des noms de ressources temporaires :

• L'ordre est important : vous ne pouvez référencer un nom de ressource temporaire qu'après l'avoir défini. Dans une liste d'opérations, l'opération dépendante (telle que la création d'un groupe d'annonces) doit apparaître après l'opération qui crée sa ressource parente (telle que la création d'une campagne).
• Champ d'application d'une seule requête ou d'un job par lot : les noms de ressources temporaires ne sont pas conservés dans des jobs ou des requêtes de modification distincts. Pour référencer une ressource créée dans un job ou une requête de mutation précédent, utilisez son nom de ressource réel généré par le système.
• Unicité globale : dans un seul job ou une seule requête de mutation, chaque nom de ressource temporaire doit utiliser un entier négatif unique pour tous les types de ressources. Par exemple, vous ne pouvez pas attribuer -1 à la fois à une campagne et à un groupe d'annonces dans la même requête. La réutilisation d'un ID temporaire dans la même requête ou le même job par lot renvoie une erreur NewResourceCreationError.DUPLICATE_TEMP_IDS.

Exemple de charge utile

Supposons que vous souhaitiez ajouter une campagne, un groupe d'annonces et une annonce dans une seule requête API ou un seul job par lot. Vous pouvez structurer le tableau mutateOperations dans une charge utile de requête GoogleAdsService.Mutate ou BatchJobService.AddBatchJobOperations, comme illustré dans l'exemple JSON REST suivant (les autres champs de ressources obligatoires sont omis par souci de concision) :

{
  "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"
        }
      }
    }
  ]
}

Cet exemple illustre les principaux détails suivants :

• Le groupe d'annonces utilise un nouvel ID temporaire (-2), car -1 est déjà attribué à la campagne.
• Le groupe d'annonces référence customers/CUSTOMER_ID/campaigns/-1 pour se lier à la campagne créée lors de l'opération précédente.
• adGroupAdOperation référence customers/CUSTOMER_ID/adGroups/-2 et omet resourceName, car aucune opération ultérieure de la requête ne référence la nouvelle annonce.

Gestion des exceptions dans les jobs par lot

Étant donné que les opérations standards d'un job par lot s'exécutent avec l'échec partiel activé (sauf dans les sous-lots atomiques), si une ressource parente avec un ID temporaire échoue à la validation, toutes les opérations enfants dépendantes qui référencent cet ID temporaire échouent avec NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. La réutilisation du même ID négatif dans plusieurs opérations create au sein du même job par lot renvoie NewResourceCreationError.DUPLICATE_TEMP_IDS. Les ID temporaires ne sont valides que lors de la création de ressources (create) ou du référencement de ressources parentes nouvellement créées. Par exemple, la transmission d'un ID temporaire négatif dans AdGroupCriterionOperation.remove lors de l'appel de AddBatchJobOperations renvoie RequestError.RESOURCE_NAME_MALFORMED.