Использовать временные идентификаторы

Временные названия ресурсов

BatchJobService поддерживает временные названия ресурсов, на которые можно ссылаться в последующих операциях в рамках одного пакетного задания, в том числе в нескольких последовательных запросах AddBatchJobOperations, загруженных с помощью sequence_token. Это позволяет создать кампанию и связанные с ней группы объявлений, объявления и критерии в одном пакетном задании до того, как будут назначены идентификаторы на стороне сервера. В приведенных ниже общих правилах и примере под одним запросом понимается весь файл BatchJob, загруженный со всеми его частями AddBatchJobOperations.

Чтобы сослаться на только что созданный ресурс в том же запросе mutate или пакетном задании, укажите отрицательное целое число (например, -1 или -2, за исключением 0) в поле resource_name нового ресурса. Например, при создании кампании в пакетном запросе задайте для нее название ресурса customers/CUSTOMER_ID/campaigns/-1. При создании группы объявлений в рамках более поздней операции в том же запросе укажите customers/CUSTOMER_ID/campaigns/-1 в качестве родительской кампании. API автоматически заменяет -1 на фактический идентификатор кампании, созданный при ее создании.

Ограничения на использование

При использовании временных названий ресурсов учитывайте следующие правила:

• Порядок имеет значение. Ссылаться на временное название ресурса можно только после того, как вы его определили. В списке операций зависимая операция (например, создание группы объявлений) должна идти после операции, которая создает ее родительский ресурс (например, создание кампании).
• Область действия одного запроса или пакетного задания. Временные названия ресурсов не сохраняются между отдельными заданиями или запросами на изменение. Чтобы сослаться на ресурс, созданный в предыдущем задании или запросе на изменение, используйте его фактическое системное имя.
• Глобальная уникальность. В рамках одного задания или запроса mutate каждое временное название ресурса должно использовать уникальное отрицательное целое число для всех типов ресурсов. Например, нельзя назначить -1 одновременно кампании и группе объявлений в одном запросе. Повторное использование временного идентификатора в одном запросе или пакетном задании приводит к ошибке NewResourceCreationError.DUPLICATE_TEMP_IDS.

Пример полезной нагрузки

Предположим, вы хотите добавить кампанию, группу объявлений и объявление в одном запросе API или пакетном задании. Вы можете структурировать массив mutateOperations в полезной нагрузке запроса GoogleAdsService.Mutate или BatchJobService.AddBatchJobOperations, как показано в следующем примере REST JSON (другие обязательные поля ресурсов опущены для краткости):

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

В этом примере показаны следующие ключевые детали:

• Группа объявлений использует новый временный идентификатор (-2), поскольку идентификатор -1 уже назначен кампании.
• Группа объявлений ссылается на customers/CUSTOMER_ID/campaigns/-1, чтобы связать себя с кампанией, созданной в предыдущей операции.
• В adGroupAdOperation есть ссылка на customers/CUSTOMER_ID/adGroups/-2, но нет ссылки на resourceName, поскольку в запросе нет операций, связанных с новым объявлением.

Обработка ошибок в пакетных заданиях

Поскольку стандартные операции в пакетном задании выполняются с включенным параметром partial failure (кроме атомарных подпакетов), если родительский ресурс с временным идентификатором не проходит проверку, все зависимые дочерние операции, ссылающиеся на этот временный идентификатор, завершаются с ошибкой NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. Если вы используете один и тот же отрицательный идентификатор в нескольких операциях create в рамках одного пакетного задания, возвращается ошибка NewResourceCreationError.DUPLICATE_TEMP_IDS. Временные идентификаторы действительны только при создании ресурсов (create) или ссылках на недавно созданные родительские ресурсы. Например, если передать отрицательный временный идентификатор в AdGroupCriterionOperation.remove при вызове AddBatchJobOperations, будет возвращен RequestError.RESOURCE_NAME_MALFORMED.