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

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

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

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

تتوفّر برامج خدمة العملاء التي تمت معالجتها بعد الإنشاء في src/Google/Ads/GoogleAds/VX/Services/Client/ (مثلاً، V25)، وتتوفّر فئات رسائل الطلبات والردود ذات الصلة (مثل 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: أدوات ضبط سلسة

$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: أدوات ضبط سلسة

$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: أدوات الضبط السلسة (موصى به)

$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])
    ])
);