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 les opérations suivantes du même job par lot, y compris dans plusieurs requêtes AddBatchJobOperations séquentielles importées avec 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 demande fait référence à l'ensemble d'un BatchJob pour tous ses AddBatchJobOperations importés.

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 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 faire référence à 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).
• Portée d'une requête unique ou d'un job par lot : les noms de ressources temporaires ne sont pas conservés entre les jobs distincts ni les requêtes de mutation. Pour référencer une ressource créée dans une tâche ou une requête de modification précédente, utilisez son nom de ressource réel généré par le système.
• Unicité globale : dans une même requête de job ou 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. Si vous réutilisez un ID temporaire dans la même requête ou le même job par lot, une erreur NewResourceCreationError.DUPLICATE_TEMP_IDS s'affiche.

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 (avec d'autres champs de ressources requis 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 fait référence à customers/CUSTOMER_ID/campaigns/-1 pour se lier à 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 dans la requête ne fait référence à la nouvelle annonce.

Gestion des erreurs dans les tâches 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 une ressource parente avec un ID temporaire échoue à la validation, toutes les opérations enfants dépendantes qui font référence à cet ID temporaire échouent avec le code d'erreur NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. La réutilisation du même ID négatif pour plusieurs opérations create dans le 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 de la référence à des 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.