Ta strona została przetłumaczona przez Cloud Translation API.

Przykłady

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

Więcej szczegółowych przykładów kodu znajdziesz w repozytorium z przykładami kodu REST na GitHubie.

Aby wyświetlić treść żądania i odpowiedzi dla każdej metody interfejsu API, zapoznaj się z dokumentacją referencyjną dotyczącą konkretnych punktów końcowych usługi.

Na przykład strona referencyjna dla GoogleAdsService.Search zawiera treść żądania i odpowiedzi dla metody Search.

Wymagania wstępne

Wszystkie przykłady podane w tym dokumencie należy skopiować i wkleić do powłoki bash za pomocą polecenia curl.

Potrzebujesz też tokena programisty (wystarczy dostęp do konta testowego) oraz konta menedżera Google Ads, które zawiera co najmniej 1 konto klienta.

Zmienne środowiskowe

Wpisz dane logowania i identyfikatory zgodnie z instrukcjami, a potem skopiuj je i wklej do terminala, aby skonfigurować zmienne środowiskowe używane w kolejnych przykładach. W przewodniku Autoryzacja znajdziesz instrukcje generowania tokena dostępu OAuth 2.0.

API_VERSION="22"
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 tych przykładów działają w przypadku dotychczasowych budżetów lub kampanii. Jeśli masz identyfikatory istniejących obiektów, których chcesz użyć w tych przykładach, wpisz je w sposób pokazany poniżej.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

W przeciwnym razie dwie operacje Mutates – Creates examples utworzą nowy budżet i nową kampanię.

Szukaj

Przewodnik Query Cookbook zawiera wiele przykładowych raportów, które odpowiadają niektórym domyślnym ekranom Google Ads i działają z tymi samymi zmiennymi środowiskowymi, które są używane w tym przewodniku. Nasze interaktywne narzędzie do tworzenia zapytań to również świetne źródło informacji o interaktywnym tworzeniu zapytań niestandardowych.

Z podziałem na strony

Metoda search korzysta z paginacji ze stałym rozmiarem strony wynoszącym 10 000 elementów i parametrem page_token określonym obok parametru 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 '{
"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'
",
"page_token":"${PAGE_TOKEN}"
}'

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'

Streaming

Metoda searchStream przesyła strumieniowo wszystkie wyniki w jednej odpowiedzi, 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'

Mutuje

Wiele operacji modyfikacji (create, update lub remove) można wysłać w jednej treści żądania JSON, wypełniając tablicę operations.

Tworzy

W tym przykładzie w ramach jednej prośby tworzone są 2 budżety wspólne kampanii.

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 użyto BUDGET_ID istniejącego budżetu kampanii. Możesz skopiować i wkleić dane wyjściowe z poprzedniego kroku.

BUDGET_ID=BUDGET_ID

Zasoby odwołujące się do innych zasobów robią to za pomocą nazwy zasobu. Kampania utworzona w poniższym przykładzie odwołuje się do campaignBudget za pomocą nazwy zasobu 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 użyto istniejącej kampanii. Możesz skopiować i wkleić dane wyjściowe z poprzedniego kroku.

CAMPAIGN_ID=CAMPAIGN_ID

Wszystkie aktualizacje wymagają pola updateMask, czyli listy atrybutów JSON oddzielonych przecinkami, które powinny być zawarte w żądaniu i zastosowane jako aktualizacja. Atrybuty wymienione w updateMask, ale nieobecne w treści żądania, są usuwane z obiektu. Atrybuty niewymienione w sekcji updateMask, ale obecne 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 przez podanie ich nazwy zasobu jako operacji 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 jednym żądaniu jest wiele operacji, możesz opcjonalnie podać parametr partialFailure. Jeśli true, operacje są wykonywane, a nieprawidłowe operacje zwracają błędy. Jeśli false, wszystkie operacje w żądaniu zakończą się powodzeniem tylko wtedy, gdy wszystkie będą prawidłowe.

W następnym przykładzie użyto istniejącej kampanii. Możesz skopiować i wkleić dane wyjściowe z przykładu tworzenia.

CAMPAIGN_ID=CAMPAIGN_ID

To żądanie zawiera 2 operacje. Pierwsza próba zmiany strategii ustalania stawek w podanej kampanii, a druga – usunięcia kampanii z nieprawidłowym identyfikatorem. Druga operacja powoduje błąd (identyfikator kampanii jest nieprawidłowy), a ponieważ parametr partialFailure ma wartość false, pierwsza operacja też się nie powiedzie, a strategia ustalania stawek w istniejącej kampanii nie zostanie zaktualizowana.

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'
  }
]
}"

Pogrupowane operacje

Metoda googleAds:mutate obsługuje wysyłanie grup operacji z wieloma typami zasobów. Możesz wysyłać wiele operacji różnych typów, aby połączyć w łańcuch sekwencję operacji, które powinny być wykonywane jako grupa. Zestaw operacji zakończy się powodzeniem, jeśli żadna z nich nie zakończy się niepowodzeniem, lub niepowodzeniem, jeśli nie powiedzie się jakakolwiek z nich.

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

Liczby całkowite ujemne (-1, -2, -3) są używane jako symbole zastępcze w nazwach zasobów i są dynamicznie wypełniane 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

Możesz tworzyć konta, wyświetlać listę kont, do których masz dostęp, i przesyłać zasoby binarne.

Tworzenie kont

Utwórz nowe konta, korzystając z metody createCustomerClient. Pamiętaj, że adres URL wymaga identyfikatora konta menedżera zamiast identyfikatora konta klienta. Na koncie menedżera zostanie utworzone 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, do których masz dostęp

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ć 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 komponentów binarnych

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

W tym przykładzie kodujemy 1-pikselowy GIF, aby zachować zwięzłość przykładu. W praktyce ładunkidata są znacznie większe.

Użyj narzędzia wiersza poleceń base64 (część podstawowych narzędzi GNU), aby zakodować 1-pikselowy obraz GIF.

base64 1pixel.gif

Wartość zakodowana w formacie Base64 jest określana jako atrybut data w żądaniu wysłanym do interfejsu API.

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'
      }
    }
  }
]
}"

Przykłady Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Wymagania wstępne

Zmienne środowiskowe

Dodatkowe opcjonalne identyfikatory obiektów

Szukaj

Z podziałem na strony

curl

GAQL

Streaming

curl

GAQL

Mutuje

Tworzy

Aktualizacje

Usuń

Częściowe niepowodzenia

Pogrupowane operacje

Zarządzanie kontem

Tworzenie kont

Wyświetlanie listy kont, do których masz dostęp

Przesyłanie komponentów binarnych

Przykłady