Przykłady

Ten przewodnik zawiera przykłady bezpośredniego wywoływania punktów końcowych REST bez użycia biblioteki klienta.

Wymagania wstępne

Wszystkie poniższe przykłady należy skopiować i wkleić w powłoce powłoki bash przy użyciu polecenia curl.

Potrzebujesz też tokena programisty, dostępu do konta testowego oraz konta menedżera Google Ads zawierającego co najmniej jedno konto klienta.

Ważne: w tych przykładach zakładamy, że dostęp do konta klienta (CUSTOMER_ID) może uzyskać użytkownik z dostępem administracyjnym do konta menedżera (MANAGER_CUSTOMER_ID) bezpośrednio zarządzającym tym kontem. Jeśli chcesz uzyskać bezpośredni dostęp do konkretnego konta klienta, pomiń nagłówek login-customer-id lub ustaw go na tę samą wartość co CUSTOMER_ID. Pamiętaj, że niektóre przykłady, takie jak tworzenie kont, wymagają konta menedżera.

Zmienne środowiskowe

Wpisz poniżej dane logowania i identyfikatory do konta, a następnie skopiuj je i wklej w terminalu, aby skonfigurować zmienne środowiskowe używane w kolejnych przykładach. Przewodnik Autoryzacja zawiera instrukcje generowania tokena dostępu OAuth 2.0.

API_VERSION="16"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"

Dodatkowe opcjonalne identyfikatory obiektów

Niektóre z poniższych przykładów dotyczą już istniejących budżetów lub kampanii. Jeśli masz identyfikatory istniejących obiektów, których chcesz użyć w tych przykładach, wpisz je poniżej.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

W przeciwnym razie dwie opcje Mutates – Tworzenie przykładów tworzą nowy budżet i kampanię.

Wyszukiwarka

Przewodnik Query Cookbook zawiera wiele przykładów raportów, które odpowiadają niektórym domyślnym ekranom Google Ads i działają z tymi samymi zmiennymi środowiskowymi, co ten przewodnik. Nasze interaktywne narzędzie do tworzenia zapytań to doskonałe narzędzie do interaktywnego tworzenia niestandardowych zapytań.

Z podziałem na strony

Metoda search używa podziału na strony z regulowanym parametrem pageSize określonym obok elementu query.

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"pageSize": 10,
"query": "
  SELECT campaign.name,
    campaign_budget.amount_micros,
    campaign.status,
    campaign.optimization_score,
    campaign.advertising_channel_type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.bidding_strategy_type
  FROM campaign
  WHERE segments.date DURING LAST_7_DAYS
    AND campaign.status != 'REMOVED'
"
}'

GAQL,

SELECT campaign.name,
  campaign_budget.amount_micros,
  campaign.status,
  campaign.optimization_score,
  campaign.advertising_channel_type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.bidding_strategy_type
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status != 'REMOVED'

transmisje

Metoda searchStream przesyła strumieniowo wszystkie wyniki w jedną odpowiedź, dlatego pole pageSize nie jest obsługiwane.

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT campaign.name,
    campaign_budget.amount_micros,
    campaign.status,
    campaign.optimization_score,
    campaign.advertising_channel_type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.bidding_strategy_type
  FROM campaign
  WHERE segments.date DURING LAST_7_DAYS
    AND campaign.status != 'REMOVED'
"
}'

GAQL,

SELECT campaign.name,
  campaign_budget.amount_micros,
  campaign.status,
  campaign.optimization_score,
  campaign.advertising_channel_type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.bidding_strategy_type
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status != 'REMOVED'

Mutacje

Przez wypełnienie tablicy operations w jednej treści żądania JSON można wysłać wiele operacji mutacji (create, update lub remove).

Tworzenie

Ten przykład tworzy 2 budżety kampanii wspólnych w jednym żądaniu.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'name': 'My Campaign Budget #${RANDOM}',
      'amountMicros': 500000,
    }
  },
  {
    'create': {
      'name': 'My Campaign Budget #${RANDOM}',
      'amountMicros': 500000,
    }
  }
]
}"

W następnym przykładzie wykorzystywany jest BUDGET_ID istniejącego budżetu kampanii. Możesz skopiować dane wyjściowe z poprzedniego kroku i je wkleić.

BUDGET_ID=BUDGET_ID

Zasoby odwołujące się do innych zasobów używają nazwy zasobu. Kampania utworzona poniżej odwołuje się do elementu campaignBudget w postaci nazwy zasobu podanej w postaci ciągu znaków.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'status': 'PAUSED',
      'advertisingChannelType': 'SEARCH',
      'geoTargetTypeSetting': {
        'positiveGeoTargetType': 'PRESENCE_OR_INTEREST',
        'negativeGeoTargetType': 'PRESENCE_OR_INTEREST'
      },
      'name': 'My Search campaign #${RANDOM}',
      'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}',
      'targetSpend': {}
    }
  }
]
}"

Aktualizacje

Aktualizuj atrybuty istniejących obiektów za pomocą operacji update. W następnym przykładzie wykorzystamy istniejącą kampanię – możesz kopiować i wklejać wyniki uzyskane w poprzednim kroku.

CAMPAIGN_ID=CAMPAIGN_ID

Wszystkie aktualizacje wymagają pola updateMask – rozdzielanej przecinkami listy atrybutów JSON, które powinny znaleźć się w żądaniu, które powinny zostać zastosowane jako aktualizacja. Atrybuty wymienione w updateMask, ale nieobecne w treści żądania, są wyczyszczone w obiekcie. Atrybuty, których nie ma w żądaniu updateMask, ale występują w treści żądania, są ignorowane.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'update': {
      'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}',
      'name': 'A changed campaign name #${RANDOM}',
    },
    'updateMask': 'name'
  }
],
}"

Usuń

Obiekty są usuwane, określając ich nazwę zasobu jako operację remove.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}'
  }
],
}"

Częściowe niepowodzenia

Jeśli w pojedynczym żądaniu znajduje się wiele operacji, opcjonalnie określ właściwość partialFailure. Jeśli ustawiona jest wartość true, wykonywane są udane operacje, a nieprawidłowe operacje zwracają błędy. Jeśli jest ustawiona wartość false, wszystkie operacje w żądaniu powiodły się tylko wtedy, gdy są prawidłowe.

W kolejnym przykładzie wykorzystano istniejącą kampanię. Możesz go skopiować i wkleić z danych wyjściowych z przykładowego przykładu tworzenia.

CAMPAIGN_ID=CAMPAIGN_ID

To żądanie zawiera 2 operacje. Najpierw podejmuje próbę zmiany strategii ustalania stawek w podanej kampanii, a następnie próbuje usunąć kampanię z nieprawidłowym identyfikatorem. Druga operacja kończy się błędem (identyfikator kampanii jest nieprawidłowy), a element partialFailure ma wartość false, więc pierwsza też kończy się niepowodzeniem, a strategia ustalania stawek w obecnej kampanii nie jest aktualizowana.

curl --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'partialFailure': false,
'operations': [
  {
    'update': {
      'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}',
      'manualCpc': {
        'enhancedCpcEnabled': false
      }
    },
    'updateMask': 'manual_cpc.enhanced_cpc_enabled'
  },
  {
    'remove': 'customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID'
  }
]
}"

Operacje pogrupowane

Metoda googleAds:mutate umożliwia wysyłanie grup operacji z wieloma typami zasobów. Możesz wysyłać wiele operacji różnego typu, aby połączyć w łańcuch sekwencję operacji, które należy wykonać jako grupę. Zbiór operacji zakończy się powodzeniem, jeśli żadna operacja nie powiedzie się lub wszystkie zakończą się niepowodzeniem w przypadku niepowodzenia którejkolwiek z operacji.

Ten przykład pokazuje, jak utworzyć budżet kampanii, kampanię, grupę reklam i reklamę jako jeden zestaw działań. Każda następna operacja zależy od poprzedniej. Jeśli któraś z nich się nie powiedzie, cała grupa operacji zakończy się niepowodzeniem.

Ujemne liczby całkowite (-1, -2, -3) są używane jako symbole zastępcze w nazwach zasobów i są wypełniane dynamicznie w czasie działania wynikami sekwencji operacji.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'mutateOperations': [
  {
    'campaignBudgetOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/campaignBudgets/-1',
        'name': 'My Campaign Budget #${RANDOM}',
        'deliveryMethod': 'STANDARD',
        'amountMicros': 500000,
        'explicitlyShared': false
      }
    }
  },
  {
    'campaignOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/campaigns/-2',
        'status': 'PAUSED',
        'advertisingChannelType': 'SEARCH',
        'geoTargetTypeSetting': {
          'positiveGeoTargetType': 'PRESENCE_OR_INTEREST',
          'negativeGeoTargetType': 'PRESENCE_OR_INTEREST'
        },
        'name': 'My Search campaign #${RANDOM}',
        'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/-1',
        'targetSpend': {}
      }
    }
  },
  {
    'adGroupOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/adGroups/-3',
        'campaign': 'customers/${CUSTOMER_ID}/campaigns/-2',
        'name': 'My ad group #${RANDOM}',
        'status': 'PAUSED',
        'type': 'SEARCH_STANDARD'
      }
    }
  },
  {
    'adGroupAdOperation': {
      'create': {
        'adGroup': 'customers/${CUSTOMER_ID}/adGroups/-3',
        'status': 'PAUSED',
        'ad': {
          'responsiveSearchAd': {
            'headlines': [
              {
                'pinned_field': 'HEADLINE_1',
                'text': 'An example headline'
              },
              {
                'text': 'Another example headline'
              },
              {
                'text': 'Yet another headline'
              }
            ],
            'descriptions': [
              {
                'text': 'An example description'
              },
              {
                'text': 'Another example description'
              }
            ],
            'path1': 'all-inclusive',
            'path2': 'deals'
          },
          'finalUrls': ['https://www.example.com']
        }
      }
    }
  }
]
}"

Zarządzanie kontem

Tworzenie kont

Utwórz nowe konta, używając metody createCustomerClient. Pamiętaj, że adres URL wymaga identyfikatora konta menedżera, a nie identyfikatora konta klienta. Do konta menedżera tworzone jest nowe konto klienta.

curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'customerClient': {
  'descriptiveName': 'My Client #${RANDOM}',
  'currencyCode': 'USD',
  'timeZone': 'America/New_York'
}
}"

Wyświetlanie listy kont z dostępem

Użyj prostego żądania GET do metody listAccessibleCustomers, aby uzyskać listę kont Google Ads dostępnych za pomocą danego tokena dostępu OAuth 2.0. W tym żądaniu nie należy używać żadnych identyfikatorów kont menedżera ani kont klientów.

curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \

Przesyłanie zasobów binarnych

Metoda assets:mutate służy do przesyłania zasobów i zarządzania nimi. Dane binarne, takie jak obraz, są kodowane jako ciąg znaków z użyciem standardowego kodowania base64 z dopełnieniem. Akceptowane jest standardowe lub bezpieczne w adresie URL kodowanie base64 z dopełnieniem lub bez niego.

W tym przykładzie koduje 1-pikselowy plik GIF, aby zachować zwięzłość. W praktyce ładunki data są znacznie większe.

Użyj narzędzia wiersza poleceń base64 (część podstawowych narzędzi GNU) do kodowania 1-pikselowego obrazu GIF.

base64 1pixel.gif

Wartość zakodowana w base64 jest określana w żądaniu do interfejsu API jako atrybut data.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'name': 'My image asset #${RANDOM}',
      'type': 'IMAGE',
      'imageAsset': {
        'data': 'R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIA'
      }
    }
  }
]
}"