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

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

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

رمز المصدر الإصدار 2 من GAPIC

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

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

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

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

البرامج التي تم إنشاؤها من خلال GAPIC والملفات ذات الصلة الإصدار الأول من GAPIC 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
 الإصدار 2 من GAPIC: ما مِن قيمة. يتم إنشاء ملف بعد المعالجة فقط.
العملاء بعد المعالجة الإصدار الأول من GAPIC 
src/Google/Ads/GoogleAds/VX/Services/
 الإصدار 2 من GAPIC 
src/Google/Ads/GoogleAds/VX/Services/Client/

الاستخدام

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

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

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

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

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

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

النمط 1 الإصدار الأول من GAPIC 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['returnTotalResultsCount' => true]
);
الإصدار 2 من GAPIC 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setReturnTotalResultsCount(true)
);
النمط 2 الإصدار الأول من GAPIC 
N/A
 الإصدار 2 من GAPIC 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setReturnTotalResultsCount(true);
$response = $googleAdsServiceClient->search($request);
النمط 3 الإصدار الأول من GAPIC 
N/A
 الإصدار 2 من GAPIC 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'return_total_results_count' => true
]);
$response = $googleAdsServiceClient->search($request);

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

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

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