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 jednym zadaniu wsadowym, zanim zostaną przypisane identyfikatory po stronie serwera. W poniższych ogólnych zasadach i przykładzie pojedyncze żądanie odnosi się do całego BatchJob we wszystkich przesłanych plikach AddBatchJobOperations.

Aby odwołać się do nowo utworzonego zasobu w tym samym żądaniu modyfikacji lub zadaniu wsadowym, w polu resource_name nowego zasobu podaj ujemny identyfikator w postaci 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łaj się do customers/CUSTOMER_ID/campaigns/-1 jako kampanii nadrzędnej. Interfejs API automatycznie zastępuje -1 rzeczywistym identyfikatorem kampanii wygenerowanym podczas jej tworzenia.

Ograniczenia użytkowania

Podczas używania tymczasowych nazw zasobów pamiętaj o tych regułach:

• Kolejność ma znaczenie: do tymczasowej nazwy zasobu możesz się odwołać dopiero po jej zdefiniowaniu. Na liście operacji operacja zależna (np. utworzenie grupy reklam) musi występować po operacji, która tworzy zasób nadrzędny (np. utworzenie kampanii).
• Zakres pojedynczego żądania lub zadania wsadowego: tymczasowe nazwy zasobów nie są zachowywane w oddzielnych zadaniach ani żądaniach modyfikacji. Aby odwołać się do zasobu utworzonego w poprzednim zadaniu lub żądaniu modyfikacji, użyj jego rzeczywistej nazwy wygenerowanej przez system.
• Unikalność globalna: w ramach pojedynczego zadania lub żądania modyfikacji każda tymczasowa nazwa zasobu musi używać unikalnej ujemnej liczby całkowitej we wszystkich typach zasobów. Nie możesz np. przypisać -1 do kampanii i grupy reklam w tym samym żądaniu. Ponowne użycie tymczasowego identyfikatora w tym samym żądaniu lub zadaniu wsadowym spowoduje błąd NewResourceCreationError.DUPLICATE_TEMP_IDS.

Przykładowy ładunek

Załóżmy, że chcesz dodać kampanię, grupę reklam i reklamę w jednym żądaniu do interfejsu API lub zadaniu wsadowym. Tablicę mutateOperations możesz ustrukturyzować w ładunku żądania GoogleAdsService.Mutate lub BatchJobService.AddBatchJobOperations, jak pokazano w tym przykładzie REST JSON (inne wymagane pola zasobów zostały pominięte dla uproszczenia):

{
  "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 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 zadaniach wsadowych

Standardowe operacje w zadaniu wsadowym są wykonywane z włączoną opcją częściowego niepowodzenia (z wyjątkiem niepodzielnych podzbiorów wsadowych). Jeśli więc zasób nadrzędny z tymczasowym identyfikatorem nie przejdzie weryfikacji, wszystkie zależne operacje podrzędne odwołujące się do tego tymczasowego identyfikatora zakończą się niepowodzeniem z błędem NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. Ponowne użycie tego samego ujemnego identyfikatora w ramach wielu operacji create w tym samym zadaniu wsadowym 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. Na przykład przekazanie ujemnego tymczasowego identyfikatora w AdGroupCriterionOperation.remove podczas wywoływania AddBatchJobOperations zwraca RequestError.RESOURCE_NAME_MALFORMED.