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 sekwencyjnych AddBatchJobOperations żądań przesłanych za pomocą sequence_token. Dzięki temu możesz utworzyć kampanię oraz powiązane z nią 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 przesłanych plikach AddBatchJobOperations.

Aby odwołać się do nowo utworzonego zasobu w ramach tego samego żądania mutate lub zadania zbiorczego, w polu resource_name nowego zasobu określ ujemny identyfikator liczby całkowitej (np. -1 lub -2, z wyłączeniem 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 tworzenia.

Ograniczenia użytkowania

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

• 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 mutate, użyj jego rzeczywistej nazwy zasobu wygenerowanej przez system.
• Globalna unikalność: W ramach jednego zadania lub żądania modyfikacji każda tymczasowa nazwa zasobu musi używać unikalnej ujemnej liczby całkowitej we wszystkich typach zasobów. Na przykład nie możesz przypisać -1 do kampanii i grupy reklam w tym samym żądaniu. Ponowne użycie tymczasowego identyfikatora w ramach tego samego żądania lub zadania zbiorczego spowoduje zwrócenie błędu 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. Możesz utworzyć tablicę mutateOperations w ładunku żądania GoogleAdsService.Mutate lub BatchJobService.AddBatchJobOperations w sposób pokazany w tym przykładzie JSON REST (inne wymagane pola zasobów 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ż -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.
• Element 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

Ponieważ standardowe operacje w zadaniu wsadowym są wykonywane z włączoną opcją częściowego niepowodzenia (z wyjątkiem atomowych podzbiorów), jeśli walidacja 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 powodu błędu NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. Ponowne użycie tego samego ujemnego identyfikatora w wielu operacjach create w ramach tego samego zadania wsadowego spowoduje zwrócenie 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 spowoduje zwrócenie błędu RequestError.RESOURCE_NAME_MALFORMED.