Utiliser des ID temporaires

Noms de ressources temporaires

BatchJobService accepte les noms de ressources temporaires qui peuvent être référencés dans les opérations ultérieures 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 et ses groupes d'annonces, annonces et critères dépendants dans un seul job par lot avant l'attribution des ID côté serveur. Dans les règles générales et l'exemple suivants, une seule requête fait référence à l'intégralité d'un BatchJob pour l'ensemble de ses importations AddBatchJobOperations.

Pour référencer une ressource nouvellement créée dans la même requête de modification 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 en tant que 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 (par exemple, la création d'un groupe d'annonces) doit apparaître après l'opération qui crée sa ressource parente (par exemple, 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 d'un job ou d'une requête de modification à l'autre. Pour référencer une ressource créée dans un job ou une requête de modification précédents, utilisez son nom de ressource réel généré par le système.
• Unicité globale : dans un même job ou une même requête de modification, 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 ont été 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 points clés suivants :

• Le groupe d'annonces utilise un nouvel ID temporaire (-2), car -1 est déjà attribué à la campagne.
• Le groupe d'annonces fait référence à customers/CUSTOMER_ID/campaigns/-1 pour s'associer à la campagne créée lors de l'opération précédente.
• adGroupAdOperation fait référence à customers/CUSTOMER_ID/adGroups/-2 et omet resourceName, car aucune opération ultérieure de la requête ne fait 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'option échec partiel activée (sauf dans les sous-lots atomiques), si la validation d'une ressource parente avec un ID temporaire échoue, toutes les opérations enfants dépendantes qui font référence à cet ID temporaire échouent avec l'erreur 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 l'erreur 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, transmettre un ID temporaire négatif dans AdGroupCriterionOperation.remove lors de l'appel de AddBatchJobOperations renvoie RequestError.RESOURCE_NAME_MALFORMED.