API جدید Search Ads 360 Reporting اکنون در دسترس است. به گروه Google searchads-api-announcements بپیوندید تا در مورد پیشرفت‌ها و نسخه‌های آینده به‌روز باشید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

با Search Ads 360 Reporting API شروع کنید

بخش‌های زیر نحوه شروع به کار با API گزارش‌دهی تبلیغات جستجو ۳۶۰ را شرح می‌دهند.

پروژه خود را در Google Cloud راه‌اندازی کنید

برای استفاده از API گزارش‌دهی تبلیغات جستجو ۳۶۰، باید یک پروژه برای برنامه خود در Google Cloud ایجاد کنید.

ایجاد یک پروژه گوگل

یک پروژه گوگل به عنوان یک مخزن منابع برای منابع گوگل کلود شما عمل می‌کند.

به کنسول API گوگل بروید.
روی ایجاد پروژه کلیک کنید.
یک نام وارد کنید یا پیشنهاد تولید شده را بپذیرید.
فیلدهای باقی مانده را تأیید یا ویرایش کنید.
روی ایجاد کلیک کنید.

ایجاد اعتبارنامه‌های OAuth2

API گزارش‌دهی Search Ads 360 از OAuth 2.0 برای احراز هویت و مجوزدهی استفاده می‌کند. اعتبارنامه‌های OAuth، برنامه شما را برای گوگل شناسایی می‌کنند و به شما امکان می‌دهند توکن‌های OAuth را برای مدیریت کاربران Search Ads 360 ایجاد کنید.

برای ایجاد اعتبارنامه OAuth 2.0 در کنسول API گوگل، موارد زیر را انجام دهید:

به صفحه مشتریان بروید.
روی ایجاد اعتبارنامه‌ها > شناسه کلاینت OAuth کلیک کنید
نوع درخواست خود را انتخاب کنید.
فرم را پر کنید و روی ایجاد کلیک کنید.

فعال کردن API گزارش‌دهی تبلیغات جستجو ۳۶۰

برای استفاده از API، باید API گزارش‌دهی تبلیغات جستجو ۳۶۰ را برای پروژه خود در کنسول API گوگل فعال کنید.

برای فعال کردن API برای پروژه خود:

کتابخانه API را در کنسول API گوگل باز کنید .
در صورت درخواست، یک پروژه را انتخاب کنید یا یک پروژه جدید ایجاد کنید. کتابخانه API تمام API های موجود را که بر اساس خانواده محصول و محبوبیت گروه بندی شده اند، فهرست می کند.
اگر API مورد نظر برای فعال‌سازی در لیست قابل مشاهده نیست، از جستجو برای یافتن آن استفاده کنید، یا روی مشاهده همه در خانواده محصولی که به آن تعلق دارد کلیک کنید.
API مورد نظر خود را انتخاب کنید و سپس روی دکمه‌ی فعال‌سازی کلیک کنید.
در صورت درخواست، صورتحساب را فعال کنید.
در صورت درخواست، شرایط خدمات API را بخوانید و بپذیرید.

به صورت اختیاری صورتحساب را برای پروژه خود فعال کنید

استفاده از API گزارش‌دهی تبلیغات جستجو ۳۶۰ در گوگل کلود هیچ هزینه‌ای ندارد. با این حال، برای هر حساب کاربری، سهمیه‌ای برای تعداد کل پروژه‌های ابری رایگان وجود دارد. اگر به حد نصاب خود رسیده‌اید، می‌توانید برای یک حساب کاربری گوگل جدید ثبت‌نام کنید که شامل سهمیه پروژه رایگان خواهد بود.

برای فعال کردن صورتحساب برای پروژه خود:

به صفحه صورتحساب مراجعه کنید.
اگر حساب صورتحساب فعالی ندارید، با کلیک روی «افزودن حساب صورتحساب» و دنبال کردن دستورالعمل‌ها، یکی ایجاد کنید.

صفحه رضایت پروژه خود را فعال کنید

برای فعال کردن صفحه رضایت پروژه خود:

صفحه برندسازی را در کنسول ابری گوگل باز کنید.
در صورت درخواست، یک پروژه را انتخاب کنید یا یک پروژه جدید ایجاد کنید.
فرم را پر کنید و روی ذخیره کلیک کنید.

ایجاد، ویرایش یا مشاهده‌ی URL(های) ریدایرکت

برای ایجاد، مشاهده یا ویرایش URI های تغییر مسیر برای یک اعتبارنامه OAuth 2.0 مشخص، موارد زیر را انجام دهید:

به صفحه مشتریان بروید.
روی کلاینت کلیک کنید.
مشاهده یا ویرایش آدرس‌های اینترنتی (URI) ریدایرکت.

اگر هیچ کلاینتی در صفحه کلاینت‌ها فهرست نشده باشد، پروژه شما فاقد اعتبارنامه OAuth است. برای ایجاد آن، روی ایجاد کلاینت کلیک کنید.

دانلود کتابخانه کلاینت

استفاده از کتابخانه کلاینت API گزارش‌دهی تبلیغات جستجو ۳۶۰، روش پیشنهادی برای اتصال به API گزارش‌دهی تبلیغات جستجو ۳۶۰ است.

کتابخانه کلاینت API گزارش‌دهی تبلیغات جستجو ۳۶۰ را برای محیط توسعه خود دانلود کنید. دستورالعمل‌های خاص زبان را در مورد نحوه تنظیم فایل پیکربندی کتابخانه کلاینت خود دنبال کنید. در بیشتر موارد، می‌توانید هنگام انتقال به کتابخانه کلاینت API گزارش‌دهی تبلیغات جستجو ۳۶۰ جدید، از پیکربندی موجود خود دوباره استفاده کنید.

یکی از تغییرات مهم، هدر جدید login-customer-id است. برای جزئیات بیشتر در مورد زمان نیاز به اضافه کردن این مورد به پیکربندی خود ، به هدر Login customer ID مراجعه کنید.

اولین تماس خود را برقرار کنید

پس از پیکربندی کتابخانه کلاینت، می‌توانید اولین تماس خود را برقرار کنید.

دریافت کمپین‌ها

در IDE خود، کد زیر را اجرا کنید:

جاوا

// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package sample;

import com.beust.jcommander.Parameter;
import com.google.ads.searchads360.v0.lib.SearchAds360Client;
import com.google.ads.searchads360.v0.services.SearchAds360Row;
import com.google.ads.searchads360.v0.services.SearchAds360ServiceClient;
import com.google.ads.searchads360.v0.services.SearchAds360ServiceClient.SearchPagedResponse;
import com.google.ads.searchads360.v0.services.SearchSearchAds360Request;

/** Get campaign details. */
public class GetCampaigns {
  private static final int PAGE_SIZE = 200;

  private static class GetCampaignsParams extends CodeSampleParams {

    @Parameter(names = "--customerId", required = true)
    private String customerId;

    @Parameter(names = "--loginCustomerId")
    private String loginCustomerId;
  }

  public static void main(String[] args) {
    GetCampaignsParams params = new GetCampaignsParams();
    if (!params.parseArguments(args)) {
      // Optional: You may pass the loginCustomerId on the command line or specify a loginCustomerId
      // here (10 digits, no dashes). If neither are set, customerId will be used as
      // loginCustomerId.
      // params.loginCustomerId = Long.parseLong("INSERT_LOGIN_CUSTOMER_ID_HERE");
    }
    final String loginCustomerId = params.loginCustomerId;
    final String customerId = params.customerId;

    try {
      // Creates a SearchAds360Client with the specified loginCustomerId. If there's
      // no loginCustomerId, customerId will be used instead.
      final SearchAds360Client searchAds360Client =
          SearchAds360Client.newBuilder()
              .setLoginCustomerId(loginCustomerId == null ? customerId : loginCustomerId)
              .fromPropertiesFile()
              .build();
      // Creates the Search Ads 360 Service client.
      SearchAds360ServiceClient client = searchAds360Client.create();
      new GetCampaigns().runExample(client, customerId);
    } catch (Exception exception) {
      System.err.printf("Failed with exception: %s%n", exception);
      exception.printStackTrace();
      System.exit(1);
    }
  }

  private void runExample(SearchAds360ServiceClient searchAds360ServiceClient, String customerId) {
    // Creates a query that retrieves all campaigns under the customerId.
    String query =
        """
        SELECT campaign.name, campaign.id, campaign.status FROM campaign
        """;
    SearchSearchAds360Request request =
        SearchSearchAds360Request.newBuilder()
            .setCustomerId(customerId)
            .setQuery(query)
            .setPageSize(PAGE_SIZE)
            .build();

    // Issues a search request.
    final SearchPagedResponse searchPagedResponse = searchAds360ServiceClient.search(request);
    for (SearchAds360Row element : searchPagedResponse.iterateAll()) {
      System.out.printf(
          "Campaign found with name '%s', ID %d, and status: %s.%n",
          element.getCampaign().getName(),
          element.getCampaign().getId(),
          element.getCampaign().getStatus());
    }
  }
}

دانلود GetCampaigns.java

پایتون

#!/usr/bin/env python
# Copyright 2022 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Retrieves campaigns for a customer using a pagination search request."""

import argparse
import traceback
from google.ads.searchads360.v0.services.types.search_ads360_service import SearchSearchAds360Request
from util_searchads360 import SearchAds360Client

_DEFAULT_PAGE_SIZE = 10000


def main(client, customer_id, page_size) -> None:
  search_ads_360_service = client.get_service()

  query = """
      SELECT
        campaign.name,
        campaign.id,
        campaign.status
      FROM campaign"""

  request = SearchSearchAds360Request()
  request.customer_id = customer_id
  request.query = query
  request.page_size = page_size

  # Issues a search request.
  results = search_ads_360_service.search(request=request)

  for row in results:
    campaign = row.campaign
    print(
        f'campaign "{campaign.name}" has id {campaign.id} and status {campaign.status.name}'
    )


if __name__ == "__main__":
  # SearchAds360Client will read the search-ads-360.yaml configuration file in
  # the home directory if none is specified.
  search_ads_360_client = SearchAds360Client.load_from_file()

  parser = argparse.ArgumentParser(
      description=("Retrieves campaigns for a customer."))
  # Arguments to provide to run the example.
  parser.add_argument(
      "-c",
      "--customer_id",
      type=str,
      required=True,
      help="The Search Ads 360 customer ID (10 digits, no dashes).",
  )

  parser.add_argument(
      "-l",
      "--login_customer_id",
      type=str,
      required=False,
      help="The Search Ads 360 login customer ID (10 digits, no dashes).",
  )

  args = parser.parse_args()

  search_ads_360_client.set_ids(args.customer_id, args.login_customer_id)

  try:
    main(search_ads_360_client, args.customer_id, _DEFAULT_PAGE_SIZE)
  except Exception:  # pylint: disable=broad-except
    traceback.print_exc()

دانلود get_campaigns.py

کنسول باید فهرستی از کمپین‌های موجود در حساب شما را چاپ کند.

از REST استفاده کنید

اگر تصمیم دارید از کتابخانه کلاینت استفاده نکنید، باید نحوه استفاده از REST را درک کنید.

اگر از REST با API قدیمی Search Ads 360 استفاده می‌کردید، اعتبارنامه‌های شما همچنان با API جدید گزارش‌دهی Search Ads 360 کار خواهند کرد. نقطه پایانی جدید و سایر جزئیات را در بخش مرجع REST بیابید.

بیشتر بدانید

درباره API گزارش‌دهی تبلیغات جستجو ۳۶۰ بیشتر بدانید