Usługa zasobów zmienia się

Korzystanie z usługi dedykowanej zasobowi to najbardziej bezpośredni sposób tworzenia, aktualizowania lub usuwania elementów jednego typu zasobu w interfejsie Google Ads API.

Punkty końcowe mutacji

Każdy zasób podlegający zmianom ma odpowiednią usługę i typ operacji. Aby zmienić zasób za pomocą dedykowanej usługi, wypełnij jedno z tych pól w operacji i wyślij je do punktu końcowego zmiany usługi:

• Utwórz (create): nowy obiekt zasobu do utworzenia.
• Aktualizacja (update): zmodyfikowany obiekt zasobu wraz z update_mask określającym zmienione pola.
• Usuń (remove): ciąg znaków resource_name docelowego zasobu do usunięcia.

Aby na przykład utworzyć nowy Campaign, wykonaj te czynności:

1. Utwórz obiekt Campaign z wybranymi atrybutami.
2. Przypisz go do pola create w CampaignOperation.
3. Wyślij operację w MutateCampaignsRequest do CampaignService.MutateCampaigns.

Ten sam wzorzec dotyczy wszystkich usług związanych z zasobami w interfejsie Google Ads API:

• AdGroup: przekaż AdGroupOperation do AdGroupService.MutateAdGroups.
• CampaignCriterion: przekaż CampaignCriterionOperation do CampaignCriterionService.MutateCampaignCriteria.

Ten ładunek JSON REST ilustruje żądanie wysłane do CampaignService.MutateCampaigns:

{
  "customerId": "CUSTOMER_ID",
  "operations": [
    {
      "create": {
        "name": "Interplanetary Cruise #1",
        "advertisingChannelType": "SEARCH",
        "status": "PAUSED",
        "manualCpc": {},
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/BUDGET_ID",
        "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING"
      }
    }
  ],
  "partialFailure": false,
  "validateOnly": false
}

Wiele operacji i ograniczeń

Ponieważ pole operations w żądaniu modyfikacji jest powtarzane, pojedyncze żądanie może zawierać wiele operacji (do 10 tys. operacji na żądanie) dotyczących tego typu zasobu. Domyślnie wszystkie operacje w żądaniu są wykonywane niepodzielnie, chyba że ustawisz parametr partial_failure na true.

Usługi dotyczące poszczególnych zasobów mają jednak 2 ważne ograniczenia:

• Pojedynczy typ zasobu: żądanie do usługi zasobów może zmieniać tylko zasoby zarządzane przez tę konkretną usługę.
• Brak tymczasowych identyfikatorów zasobów i odwołań do innych zasobów: operacje w wywołaniu mutacji dotyczącym konkretnego zasobu są przetwarzane niezależnie. Nie możesz przypisywać tymczasowych identyfikatorów ujemnych (np. customers/CUSTOMER_ID/campaigns/-1) ani odwoływać się do nowo utworzonych elementów z innych operacji w ramach tego samego żądania.

Jeśli w jednym żądaniu musisz zmieniać wiele typów zasobów lub odwoływać się do tymczasowych nazw zasobów w operacjach zależnych, użyj GoogleAdsService.Mutate.

Różnice w poszczególnych wersjach

Podczas modyfikowania zasobów pamiętaj o tych różnicach między obsługiwanymi wersjami interfejsu Google Ads API:

• Usługi związane z celami dotyczącymi cyklu życia: w wersji 25 i nowszych wszystkie cele związane z cyklem życia, w tym pozyskiwanie nowych klientów (new_customer_acquisition_goal_settings), utrzymanie klientów (retention_goal_settings) i utrzymanie lojalności (loyalty_retention_goal_settings), są modyfikowane za pomocą funkcji GoalService.MutateGoals i CampaignGoalConfigService.MutateCampaignGoalConfigs z użyciem standardowego powtarzanego pola operations. Zastępuje to parametry CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals i CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals (które są używane do pozyskiwania nowych klientów w wersji 24 i starszych oraz akceptują pojedyncze pole operation).
• Pola daty i godziny kampanii: podczas tworzenia lub aktualizowania Campaign w wersji 23 i nowszych używane są pola start_date_time i end_date_time (yyyy-MM-dd HH:mm:ss), które zastępują pola start_date i end_date zawierające tylko datę, używane w wersji 22.
• Zmienność atestu treści syntetycznych: chociaż pola Asset.synthetic_content_info i Ad.synthetic_content_info występują w schemacie wersji 22 i nowszych, pola synthetic_content_info.advertiser_attestation.status i synthetic_content_info.advertiser_attestation.source można zmieniać tylko w wersji 23 i nowszych (pole system_attestation zawsze ma wartość OUTPUT_ONLY). Próba zmiany pól podrzędnych advertiser_attestation w wersji 22 zwraca błąd pola niezmiennego ("The field attempted to be mutated is immutable" lub "Field cannot be set").