التهيئة

تبحث مكتبة برامج Java عن ملف إعداد باسم ads.properties في دليلك الرئيسي (System.getProperty("user.home") + "/ads.properties" أو ~/ads.properties). يمكنك إلغاء هذا المسار واسم الملف في وقت التشغيل عند إنشاء GoogleAdsClient باستخدام إحدى الآليتَين التاليتَين:

  • استخدِم الأمر fromPropertiesFile(PATH_TO_CONFIG_FILE)، حيث يمثّل PATH_TO_CONFIG_FILE مسار واسم ملف الإعداد File.
  • اضبط متغيّر البيئة GOOGLE_ADS_CONFIGURATION_FILE_PATH على مسار ملف الإعداد واسمه، ثم استدعِ fromPropertiesFile().

تنسيق ملف الإعداد هو ملف Properties عادي بلغة Java يتضمّن أزواجًا من المفاتيح والقيم. تختلف المفاتيح المتوافقة حسب مسار المصادقة الذي تم اختياره.

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

إذا كنت تستخدم مسار تطبيق المستخدم الفردي أو تعدد المستخدمين، تكون المفاتيح المتوافقة كما يلي:

# Credential for accessing Google's OAuth servers.
# Provided by console.cloud.google.com.
api.googleads.clientId=INSERT_CLIENT_ID_HERE

# Credential for accessing Google's OAuth servers.
# Provided by console.cloud.google.com.
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE

# Renewable OAuth credential associated with 1 or more Google Ads accounts.
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE

# Required for manager accounts only: Specify the login customer ID used to
# authenticate API calls. This will be the customer ID of the authenticated
# manager account. You can also specify this later in code if your application
# uses multiple manager account + OAuth pairs.
#
# api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

# Only required if explicitly instructed by the service documentation.
# api.googleads.linkedCustomerId=INSERT_LINKED_CUSTOMER_ID_HERE

# Maximum allowed response payload size, in bytes.
# Customize this to allow response sizes for GoogleAdsService.search and
# GoogleAdsService.searchStream API calls to exceed the default limit of 64MB.
# api.googleads.maxInboundMessageBytes=INSERT_MAX_INBOUND_MESSAGE_BYTES_HERE

# Specifies whether to use Application Default Credentials.
api.googleads.useApplicationDefaultCredentials=false

المفاتيح المتوافقة مع حسابات الخدمة

إذا كنت تستخدم مسار حساب الخدمة، تكون المفاتيح المتوافقة كما يلي:

# Path to the service account secrets file in JSON format.
# Provided by console.cloud.google.com.
api.googleads.serviceAccountSecretsPath=INSERT_PATH_TO_JSON_HERE

# Optional: Email address of the user to impersonate when using Google Workspace
# domain-wide delegation. This should be a user who has access to your Google Ads
# account and is in the same Google Workspace domain as the service account.
# api.googleads.serviceAccountUser=INSERT_USER_EMAIL_ADDRESS_HERE

# Required for manager accounts only: Specify the login customer ID used to
# authenticate API calls. This will be the customer ID of the authenticated
# manager account. You can also specify this later in code if your application
# uses multiple manager account + OAuth pairs.
#
# api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

استخدام متغيّرات البيئة

تتيح المكتبة استخدام جميع متغيرات بيئة مكتبة برامج Google Ads API العادية. يوضّح الجدول التالي متغيّر البيئة الذي يتوافق مع كل سمة من سمات ملف الإعداد:

خاصية ملف الإعداد متغيّر البيئة
api.googleads.clientId GOOGLE_ADS_CLIENT_ID
api.googleads.clientSecret GOOGLE_ADS_CLIENT_SECRET
api.googleads.refreshToken GOOGLE_ADS_REFRESH_TOKEN
api.googleads.serviceAccountSecretsPath GOOGLE_ADS_JSON_KEY_FILE_PATH
api.googleads.serviceAccountUser GOOGLE_ADS_IMPERSONATED_EMAIL
api.googleads.loginCustomerId GOOGLE_ADS_LOGIN_CUSTOMER_ID
api.googleads.linkedCustomerId GOOGLE_ADS_LINKED_CUSTOMER_ID
api.googleads.maxInboundMessageBytes GOOGLE_ADS_MAX_INBOUND_MESSAGE_BYTES
api.googleads.useApplicationDefaultCredentials GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS
‫api.googleads.developerToken (اختيارية في الإصدار v46.0.0 والإصدارات الأحدث) GOOGLE_ADS_DEVELOPER_TOKEN

بعد ضبط متغيّرات البيئة المناسبة، اضبط GoogleAdsClient من خلال استدعاء fromEnvironment() في أداة الإنشاء:

GoogleAdsClient googleAdsClient =
    GoogleAdsClient.newBuilder()
        .fromEnvironment()
        .build();

الجمع بين طُرق الإعداد

تتيح السمة GoogleAdsClient وأداة الإنشاء الخاصة بها إمكانية الجمع بين استراتيجيات إعدادات مختلفة. على سبيل المثال، يمكنك استخدام متغيرات البيئة لضبط بيانات اعتماد المثيل وملف خصائص للسمات الأخرى باستخدام المقتطف التالي:

GoogleAdsClient googleAdsClient =
    GoogleAdsClient.newBuilder()
        .fromEnvironment()
        .fromPropertiesFile()
        .build();

يمكنك إجراء المزيد من التغييرات في وقت التشغيل باستخدام طرق الضبط الأخرى الخاصة بأداة الإنشاء قبل استدعاء build().

إيقاف الرمز المميز للمطوِّر نهائيًا

بعد إيقاف الرمز المميّز للمطوّر نهائيًا في 9 سبتمبر 2026، سيتم تحديد مستويات الوصول إلى واجهة برمجة التطبيقات من خلال مشروعك على Google Cloud على خادم واجهة برمجة التطبيقات بدلاً من الرمز المميّز للمطوّر:

  • تغييرات في الإعدادات: لم يعُد عليك تحديد api.googleads.developerToken في ads.properties أو GOOGLE_ADS_DEVELOPER_TOKEN في متغيّرات البيئة. ستستمر التطبيقات الحالية التي لا تزال تحدّد api.googleads.developerToken في العمل لأنّ خوادم واجهة برمجة التطبيقات تتجاهل العنوان developer-token (مع أنّ إصدارًا رئيسيًا مستقبليًا من Google Ads API سيرفضه).
  • متطلبات إصدار مكتبة البرامج: لإغفال الرمز المميز للمطوِّر من الإعدادات، استخدِم الإصدار google-ads-java v46.0.0 أو إصدارًا أحدث، إذ تمت إزالة ميزة التحقّق من جهة العميل التي تتطلّب الرمز المميز للمطوِّر.
  • تغييرات في خطأ التفويض: إذا كان مشروع على Google Cloud لديه إذن وصول إلى حساب تجريبي فقط يستدعي حسابًا إنتاجيًا على "إعلانات Google"، ستعرض الإصدارات v25 والإصدارات الأحدث من Google Ads API الرمز AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION، بينما تعرض الإصدارات v24 والإصدارات الأقدم الرمز AuthorizationError.ACTION_NOT_PERMITTED.