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

رمز مصدر GAPIC v2

منذ الإصدار v20.1.0، تتضمّن مكتبة العملاء أيضًا إصدارًا جديدًا من رمز المصدر GAPIC في src/Google/Ads/GoogleAds/vX يتيح تمرير عنصر طلب إلى طرق برامج الخدمة. يُعرَف هذا الإصدار الجديد المُسمى GAPIC v2 أيضًا بالاستعداد للميزات الجديدة في المستقبل. لا يزال يتم إنشاء وتضمين رمز مصدر GAPIC السابق، وهو الإصدار 1، من GAPIC حتى نهاية عام 2023.

تتيح لك مكتبة برامج لغة PHP في Google Ads API اختيار الإصدار الذي تريد ربطه بخدمة GoogleAdsClient باستخدام إعداد الضبط useGapicV2Source. عند ضبط هذا الإعداد على true، تُنشئ مكتبة البرامج عنصر GoogleAdsClient ينشئ برامج خدمة GAPIC v2.

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

في ما يلي الاختلافات في مواقع الملفات بين إصدارات GAPIC لنوعي الفئات:

البرامج التي تم إنشاؤها بواسطة GAPIC والملفات ذات الصلة الإصدار 1 من GAPIC 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
الإصدار 2 من GAPIC: لا شيء. ولا يتم إنشاء سوى ملف تمت معالجته لاحقًا.
العملاء بعد المعالجة GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

الاستخدام

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

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

يقارن الرمز النموذجي التالي بين استدعاء CampaignService::mutate() في GAPIC الإصدار 1 و2. تجدر الإشارة إلى أنّ جميع المَعلمتَين ($customerId و$operations) هي مَعلمات مطلوبة، لذلك يتم إنشاء build() التي تقبل كلتا المَعلمتَين في رمز GAPIC v2.

النمط 1 GAPIC v1 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    $customerId,
    $campaignOperations
);
GAPIC v2 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build(
      $customerId,
      $campaignOperations
    )
);
النمط 2 GAPIC v1 
N/A
GAPIC v2 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$request = (new MutateCampaignsRequest())
    ->setCustomerId($customerId)
    ->setCampaignOperations($campaignOperations);
$response = $campaignServiceClient->mutateCampaigns($request);

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

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

النمط 1 GAPIC v1 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['pageSize' => self::PAGE_SIZE]
);
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setPageSize(self::PAGE_SIZE)
);
النمط 2 GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setPageSize(self::PAGE_SIZE);
$response = $googleAdsServiceClient->search($request);
النمط 3 GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'page_size' => self::PAGE_SIZE
]);
$response = $googleAdsServiceClient->search($request);

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

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

النمط 1 GAPIC v1 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants([
    'locale' => $locale,
    'countryCode' => $countryCode,
    'locationNames' => new LocationNames(['names' => $locationNames])
]);
GAPIC v2 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$request = (new SuggestGeoTargetConstantsRequest())
    ->setLocale($locale)
    ->setCountryCode($countryCode)
    ->setLocationNames(new LocationNames(['names' => $locationNames]));
$response =
    $geoTargetConstantServiceClient->suggestGeoTargetConstants($request);
النمط 2 GAPIC v1 
N/A
GAPIC v2 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
    new SuggestGeoTargetConstantsRequest([
        'locale' => $locale,
        'country_code' => $countryCode,
        'location_names' => new LocationNames(['names' => $locationNames])
    ])
);