Zmień

Uwaga: aby zobaczyć bardziej kompletne przykłady, przejdź do sekcji Mutates w dołączonych przykładach.

Większość zasobów jest modyfikowana (tworzona, aktualizowana lub usuwana) za pomocą metody Mutate. Metoda Mutate jest wywoływana jako HTTP POST do adresu URL zasobu, który pasuje do wzoru nazwy zasobu, bez końcowego identyfikatora zasobu. Identyfikatory zasobów, które mają zostać zmutowane, są zamiast tego wysyłane w treści żądania JSON. Dzięki temu możesz wysłać pojedyncze wywołanie interfejsu API, które zawiera wiele operacji na różnych zasobach.

Na przykład nazwa zasobu kampanii ma taki format:

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

Aby uzyskać adres URL używany do modyfikowania kampanii, pomiń końcowy identyfikator zasobu i dodaj :mutate:

https://googleads.googleapis.com/v19/customers/CUSTOMER_ID/campaigns:mutate

Wiadomość Mutate zawiera obiekt JSON najwyższego poziomu z tablicą operations, która może zawierać wiele obiektów operation. Każda operacja może być jedną z tych operacji: create, update lub remove. To jedyne możliwe operacje mutate.

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    ...
  ]
}

Większość usług obsługuje tysiące operacji w ramach jednego wywołania interfejsu API. W przewodniku Ograniczenia systemu znajdziesz informacje o ograniczeniach dotyczących rozmiarów żądań.

Operacje w ramach pojedynczego żądania do interfejsu API są domyślnie wykonywane jako jeden zestaw działań, co oznacza, że albo wszystkie się udają, albo cała partia kończy się niepowodzeniem, jeśli nie powiedzie się choćby jedna operacja. Niektóre usługi obsługują atrybut partialFailure, który umożliwia zmianę tego zachowania. Więcej informacji o semantyce operacji mutowania znajdziesz w artykule Mutowanie zasobów.

Utwórz

Operacje tworzenia tworzą nowe elementy i muszą zawierać pełne odwzorowanie zasobu w formacie JSON.

Ważne: operacje tworzenia nie określają wartości resourceName ani identyfikatora. Jeśli wywołanie interfejsu API się powiedzie, odpowiedź będzie zawierać resourceName wygenerowany dla nowo utworzonego obiektu.

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
    "create": {
        "name": "An example campaign",
        "status": "PAUSED",
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/CAMPAIGN_BUDGET_ID",
        "advertisingChannelType": "SEARCH",
        "networkSettings": {
          "targetGoogleSearch": true,
          "targetSearchNetwork": true,
          "targetContentNetwork": true,
          "targetPartnerSearchNetwork": false
        },
        "target_spend": {}
      }
    }
  ]
}

Aktualizuj

Operacje aktualizacji wykonują nieregularne aktualizacje istniejącego zasobu. Wystarczy, że określisz pola, które chcesz zmodyfikować.

Aby określić pola, które chcesz zaktualizować, ustaw atrybut updateMask na listę nazw pól rozdzielonych przecinkami. Jest to szczególnie przydatne, jeśli masz już w pełni ukształtowaną reprezentację obiektu w formacie JSON (np. zwróconą przez poprzednie wywołanie interfejsu API), ale chcesz zmienić tylko niektóre pola. Zamiast skracać obiekt JSON, możesz podać tylko nazwy pól, które mają zostać zmodyfikowane w obiekcie updateMask, i wysłać cały obiekt JSON.

Ważna informacja: update_mask to standardowe pole używane w interfejsach Google API w celu ułatwienia częściowych aktualizacji danego zasobu. Aby dowiedzieć się więcej, zapoznaj się z dokumentacją FieldMask.

W przykładzie poniżej zmieniamy name i status w istniejącej kampanii o danej resourceName.

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
      "updateMask": "name,status",
      "update": {
        "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID",
        "name": "My renamed campaign",
        "status": "PAUSED",
      }
    }
  ]
}

Usuń

Operacje usuwania powodują trwałe usunięcie obiektu i ustawienie jego stanu w Google Ads na REMOVED. Wymagany jest tylko resourceName, który ma zostać usunięty.

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
      "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID"
    }
  ]
}