واجهة برمجة التطبيقات (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/.

الاستخدام

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

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

يوضّح الرمز النموذجي التالي كيفية طلب CampaignService::mutate(). جميع المَعلمات ($customerId و$operations) مطلوبة، لذا يتم إنشاء 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])
    ])
);