أصبحت Search Ads 360 Reporting API الجديدة متاحة الآن. يمكنك الانضمام إلى مجموعة Google searchads-api-announcements لتبقى على اطّلاع على التحسينات والإصدارات القادمة.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

بدء استخدام Search Ads 360 Reporting API

توضّح الأقسام التالية كيفية بدء استخدام Search Ads 360 Reporting API.

إعداد مشروعك على Google Cloud

لاستخدام Search Ads 360 Reporting API، عليك إنشاء مشروع لتطبيقك على Google Cloud.

إنشاء مشروع على Google

يعمل مشروع Google كحاوية موارد لمواردك على Google Cloud.

انتقِل إلى وحدة التحكم في واجهة Google API.
انقر على إنشاء مشروع.
أدخِل اسمًا أو اقبل الاقتراح الذي تم إنشاؤه.
أكِّد أي حقول متبقية أو عدِّلها.
انقر على إنشاء.

إنشاء بيانات اعتماد OAuth 2.0

تستخدم Search Ads 360 Reporting API بروتوكول OAuth 2.0 للمصادقة والتفويض. تحدّد بيانات اعتماد OAuth تطبيقك لشركة Google، وتسمح لك بإنشاء رموز OAuth المميزة لإدارة مستخدمي "إعلانات شبكة البحث 360".

لإنشاء بيانات اعتماد OAuth 2.0 في وحدة التحكم في واجهة Google API، اتّبِع الخطوات التالية:

انتقِل إلى صفحة العملاء.
انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth
اختَر نوع تطبيقك.
املأ النموذج وانقر على إنشاء.

تفعيل Search Ads 360 Reporting API

لاستخدام واجهة برمجة التطبيقات، عليك تفعيل Search Ads 360 Reporting API لمشروعك في وحدة التحكم في واجهة Google API.

لتفعيل واجهة برمجة تطبيقات لمشروعك:

افتح مكتبة واجهات برمجة التطبيقات في وحدة التحكم في واجهة Google API.
إذا طُلب منك ذلك، اختَر مشروعًا أو أنشئ مشروعًا جديدًا. تعرض مكتبة واجهات برمجة التطبيقات جميع واجهات برمجة التطبيقات المتاحة، مجمّعة حسب مجموعة المنتجات والشهرة.
إذا لم تظهر واجهة برمجة التطبيقات التي تريد تفعيلها في القائمة، استخدِم ميزة البحث للعثور عليها أو انقر على عرض الكل في مجموعة المنتجات التي تنتمي إليها.
اختَر واجهة برمجة التطبيقات التي تريد تفعيلها، ثم انقر على الزر تفعيل.
إذا طُلب منك ذلك، فعِّل الفوترة.
إذا طُلب منك ذلك، اقرأ بنود خدمة واجهة برمجة التطبيقات ووافِق عليها.

تفعيل الفوترة لمشروعك بشكل اختياري

لا يتم تحصيل أي رسوم مقابل استخدام Search Ads 360 Reporting API في Google Cloud. ومع ذلك، هناك حصة إجمالية لعدد مشاريع Cloud المجانية لكل حساب. إذا بلغت الحدّ الأقصى، يمكنك الاشتراك في حساب جديد على Google يتضمّن حصة مجانية للمشاريع.

لتفعيل الفوترة لمشروعك:

انتقِل إلى صفحة الفوترة.
إذا لم يكن لديك حساب فوترة نشط، أنشئ حسابًا بالنقر على إضافة حساب فوترة واتّباع التعليمات.

تفعيل شاشة طلب الموافقة لمشروعك

لتفعيل شاشة طلب الموافقة لمشروعك:

افتح صفحة العلامة التجارية في Google Cloud Console.
إذا طُلب منك ذلك، اختَر مشروعًا أو أنشئ مشروعًا جديدًا.
املأ النموذج وانقر على حفظ.

إنشاء عناوين URI لإعادة التوجيه أو تعديلها أو عرضها

لإنشاء عناوين URI لإعادة التوجيه لبيانات اعتماد OAuth 2.0 معيّنة أو عرضها أو تعديلها، اتّبِع الخطوات التالية:

انتقِل إلى صفحة العملاء.
انقر على العميل.
اعرض عناوين URI لإعادة التوجيه أو عدِّلها.

إذا لم يكن هناك عميل مُدرَج في صفحة "العملاء"، يعني ذلك أنّ مشروعك لا يتضمّن بيانات اعتماد OAuth. لإنشاء بيانات اعتماد، انقر على إنشاء عميل.

تنزيل مكتبة برامج

إنّ استخدام مكتبة برامج Search Ads 360 Reporting API هو الطريقة المُفضّلة للاتصال بواجهة برمجة التطبيقات.

نزِّل مكتبة برامج Search Ads 360 Reporting API لبيئة التطوير. اتّبِع التعليمات الخاصة باللغة حول كيفية إعداد ملف إعداد مكتبة البرامج. في معظم الحالات، يمكنك إعادة استخدام الإعدادات الحالية عند نقل البيانات إلى مكتبة برامج Search Ads 360 Reporting API الجديدة.

أحد التغييرات المهمة هو عنوان login-customer-id الجديد. اطّلِع على عنوان معرّف العميل لتسجيل الدخول للحصول على تفاصيل حول الحالات التي تحتاج فيها إلى إضافة هذا العنوان إلى الإعدادات.

إجراء أول طلب

بعد إعداد مكتبة البرامج، يمكنك إجراء أول طلب.

الحصول على الحملات

في بيئة التطوير المتكاملة، نفِّذ الرمز التالي:

جافا

// 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

Python

#!/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 مع Search Ads 360 API القديمة، ستظل بيانات اعتمادك تعمل مع Search Ads 360 Reporting API الجديدة. يمكنك العثور على نقطة النهاية الجديدة وتفاصيل أخرى في قسم مرجع REST.

مزيد من المعلومات

مزيد من المعلومات عن Search Ads 360 Reporting API