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

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

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

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

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

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

• Порядок имеет значение: вы можете ссылаться на имя временного ресурса только после того, как определите его. В списке операций зависимая операция (например, создание группы объявлений) должна располагаться после операции, которая создает родительский ресурс (например, создание кампании).
• Область действия — отдельный запрос или пакетное задание: временные имена ресурсов не сохраняются между отдельными заданиями или запросами на изменение. Для ссылки на ресурс, созданный в предыдущем задании или запросе на изменение, используйте его фактическое имя, сгенерированное системой.
• Глобальная уникальность: в рамках одного задания или запроса на изменение каждое имя временного ресурса должно использовать уникальное отрицательное целое число для всех типов ресурсов. Например, нельзя присвоить -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 отсутствует, поскольку ни одна последующая операция в запросе не ссылается на новое объявление.

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

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