Używanie tymczasowych identyfikatorów

Tymczasowe nazwy zasobów

BatchJobService obsługuje tymczasowe nazwy zasobów, do których można się odwoływać w kolejnych operacjach w ramach tego samego zadania wsadowego, w tym w wielu kolejnych żądaniach AddBatchJobOperations przesłanych za pomocą sequence_token. Dzięki temu możesz utworzyć kampanię i zależne od niej grupy reklam, reklamy i kryteria w ramach jednego zadania wsadowego, zanim zostaną przypisane identyfikatory po stronie serwera. W poniższych zasadach ogólnych i przykładzie pojedyncze żądanie odnosi się do całego BatchJob we wszystkich jego AddBatchJobOperations.

Aby odwołać się do nowo utworzonego zasobu w ramach tego samego żądania modyfikacji lub zadania wsadowego, w polu resource_name nowego zasobu podaj ujemny identyfikator liczby całkowitej (np. -1 lub -2, z wyjątkiem 0). Na przykład podczas tworzenia kampanii w żądaniu zbiorczym ustaw jej nazwę zasobu na customers/CUSTOMER_ID/campaigns/-1. Podczas tworzenia grupy reklam w późniejszej operacji w ramach tego samego żądania odwołuj się do customers/CUSTOMER_ID/campaigns/-1 jako kampanii nadrzędnej. Interfejs API automatycznie zastępuje symbol -1 faktycznym identyfikatorem kampanii wygenerowanym podczas jej tworzenia.

Ograniczenia użytkowania

Korzystając z tymczasowych nazw zasobów, pamiętaj o tych regułach:

• Kolejność ma znaczenie: możesz odwoływać się do tymczasowej nazwy zasobu tylko po jej zdefiniowaniu. Na liście operacji operacja zależna (np. utworzenie grupy reklam) musi występować po operacji, która tworzy jej zasób nadrzędny (np. utworzenie kampanii).
• Zakres pojedynczego żądania lub zadania wsadowego: tymczasowe nazwy zasobów nie są zachowywane w przypadku oddzielnych zadań ani żądań modyfikacji. Aby odwołać się do zasobu utworzonego w poprzednim zadaniu lub żądaniu modyfikacji, użyj jego wygenerowanej przez system nazwy zasobu.
• Globalna niepowtarzalność: w ramach jednego zadania lub żądania modyfikacji każdy tymczasowy identyfikator zasobu musi używać unikalnej liczby całkowitej ujemnej we wszystkich typach zasobów. Nie możesz na przykład przypisać -1 do kampanii i grupy reklam w tym samym żądaniu. Ponowne użycie tymczasowego identyfikatora w ramach tej samej prośby lub zadania wsadowego zwraca błąd NewResourceCreationError.DUPLICATE_TEMP_IDS.

Przykładowy ładunek

Załóżmy, że chcesz dodać kampanię, grupę reklam i reklamę w ramach jednego żądania API lub zadania wsadowego. Tablicę mutateOperations możesz ustrukturyzować w treści żądania GoogleAdsService.Mutate lub BatchJobService.AddBatchJobOperations, jak pokazano w tym przykładzie JSON REST (inne wymagane pola zasobu zostały pominięte dla zwięzłości):

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

Ten przykład pokazuje te kluczowe szczegóły:

• Grupa reklam używa nowego tymczasowego identyfikatora (-2), ponieważ identyfikator -1 jest już przypisany do kampanii.
• Grupa reklam odwołuje się do wartości customers/CUSTOMER_ID/campaigns/-1, aby połączyć się z kampanią utworzoną w poprzedniej operacji.
• adGroupAdOperation odwołuje się do customers/CUSTOMER_ID/adGroups/-2 i pomija resourceName, ponieważ żadna kolejna operacja w żądaniu nie odwołuje się do nowej reklamy.

Obsługa błędów w przypadku zadań zbiorczych

Ponieważ standardowe operacje w zadaniu wsadowym są wykonywane z włączoną opcją częściowego niepowodzenia (z wyjątkiem atomowych podzadań wsadowych), jeśli weryfikacja zasobu nadrzędnego z tymczasowym identyfikatorem nie powiedzie się, wszystkie zależne operacje podrzędne odwołujące się do tego tymczasowego identyfikatora zakończą się niepowodzeniem z kodem NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. Ponowne użycie tego samego identyfikatora ujemnego w wielu operacjach create w ramach tego samego zadania wsadowego zwraca błąd NewResourceCreationError.DUPLICATE_TEMP_IDS. Tymczasowe identyfikatory są prawidłowe tylko podczas tworzenia zasobów (create) lub odwoływania się do nowo utworzonych zasobów nadrzędnych, np. przekazywanie ujemnego tymczasowego identyfikatora w AdGroupCriterionOperation.remove podczas wywoływania AddBatchJobOperations zwraca RequestError.RESOURCE_NAME_MALFORMED.