واجهة برمجة التطبيقات (GAPIC)

يتم إنشاء الرمز المصدر في الدليل src/Google/Ads/GoogleAds/VX لمكتبة عميل PHP في Google Ads API تلقائيًا باستخدام أداة إنشاء GAPIC (عميل واجهة برمجة التطبيقات الذي تم إنشاؤه)، استنادًا إلى ملفات proto المنشورة، حيث يمثّل X رقم إصدار Google Ads API.

يتم بعد ذلك تعديل الرمز المصدر الذي تم إنشاؤه ليحتوي على مراجع للسمات والفئات المطلوبة لإنشاء عملاء الخدمة الذين يعملون مع Google Ads API باستخدام الفئة GoogleAdsClient التي يتم إنشاؤها من خلال استدعاء GoogleAdsClientBuilder::build(). يتم الاحتفاظ بكل من GoogleAdsClient وGoogleAdsClientBuilder يدويًا في src/Google/Ads/GoogleAds/Lib/VX/.

المواقع الجغرافية التي تم إنشاؤها للصفوف

توجد برامج الخدمة التي تمت معالجتها لاحقًا في src/Google/Ads/GoogleAds/VX/Services/Client/ (على سبيل المثال، V26)، وتوجد فئات رسائل الطلب والاستجابة المقابلة (مثل MutateCampaignsRequest وSearchGoogleAdsRequest) في src/Google/Ads/GoogleAds/VX/Services/. يتم إنشاء إصدارات واجهة برمجة التطبيقات الثانوية (مثل v25.1) داخل دليل رقم الإصدار الرئيسي (V25).

الاستخدام

يجب إنشاء عنصر طلب وتمريره إلى عميل الخدمة الذي تريد استخدامه. استنادًا إلى ما إذا كانت المَعلمات مطلوبة أو اختيارية، تتوفّر لك طرق متعددة لإنشاء عنصر طلب، بما في ذلك طريقة المصنع الثابتة build() لتمرير المَعلمات المطلوبة.

المثال 1.1: الطرق التي تتضمّن مَعلمات مطلوبة

يوضّح الرمز النموذجي التالي كيفية استدعاء CampaignServiceClient::mutateCampaigns(). بما أنّ كلّاً من $customerId و$campaignOperations هما مَعلمتان مطلوبتان، يتم إنشاء طريقة مصنع build() ثابتة تقبل كلتا المَعلمتَين في فئة الطلب.

النمط 1: طريقة الإنشاء الثابتة (يُنصح بها)

$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build(
        $customerId,
        $campaignOperations
    )
);

النمط 2: دوال setter سلسة

$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$request = (new MutateCampaignsRequest())
    ->setCustomerId($customerId)
    ->setCampaignOperations($campaignOperations);
$response = $campaignServiceClient->mutateCampaigns($request);

المثال 1.2: الطرق التي تتضمّن مَعلمات مطلوبة واختيارية

يستدعي الرمز النموذجي التالي GoogleAdsServiceClient::search(). في هذا المثال، تقبل طريقة build() التي تم إنشاؤها مَعلمتَين فقط ($customerId و$query) لأنّهما مَعلمتان مطلوبتان. لطلب العدد الإجمالي للنتائج التي تطابق طلب البحث مع تجاهل عبارة LIMIT، يمكنك ضبطه صراحةً باستخدام setReturnTotalResultsCount(). يمكنك بدلاً من ذلك تمرير جميع المَعلمات معًا في مصفوفة ترابطية إلى الدالة الإنشائية لـ SearchGoogleAdsRequest، كما هو موضّح في النمط 3.

النمط 1: طريقة الإنشاء الثابتة مع طرق الضبط السلسة

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setReturnTotalResultsCount(true)
);

النمط 2: دوال setter سلسة

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setReturnTotalResultsCount(true);
$response = $googleAdsServiceClient->search($request);

النمط 3: دالة إنشاء المصفوفة

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$request = new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'return_total_results_count' => true
]);
$response = $googleAdsServiceClient->search($request);

المثال 2: طرق تتضمّن معلَمات اختيارية فقط

يوضّح هذا المثال كيفية استدعاء GeoTargetConstantServiceClient::suggestGeoTargetConstants(). بما أنّ جميع مَعلمات GeoTargetConstantServiceClient::suggestGeoTargetConstants() اختيارية، لا يتم إنشاء build() في الرمز المصدر في هذه الحالة، وعليك إنشاء عنصر الطلب باستخدام دوال الضبط أو الدالة الإنشائية للمصفوفة.

النمط 1: دوال setter سلسة (يُنصح بها)

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$request = (new SuggestGeoTargetConstantsRequest())
    ->setLocale($locale)
    ->setCountryCode($countryCode)
    ->setLocationNames(new LocationNames(['names' => $locationNames]));
$response =
    $geoTargetConstantServiceClient->suggestGeoTargetConstants($request);

النمط 2: دالة إنشاء المصفوفة

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
    new SuggestGeoTargetConstantsRequest([
        'locale' => $locale,
        'country_code' => $countryCode,
        'location_names' => new LocationNames(['names' => $locationNames])
    ])
);