تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

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

البرامج التي تم إنشاؤها من خلال GAPIC والملفات ذات الصلة

الإصدار 1 من GAPIC

src/Google/Ads/GoogleAds/VX/Services/Gapic/

الإصدار 2 من GAPIC: لا ينطبق. يتم إنشاء ملف بعد المعالجة فقط.

العملاء بعد المعالجة

الإصدار 1 من GAPIC

src/Google/Ads/GoogleAds/VX/Services/

الإصدار 2 من GAPIC

src/Google/Ads/GoogleAds/VX/Services/Client/

الاستخدام

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

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

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

النمط 1

الإصدار 1 من GAPIC

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

الإصدار 2 من GAPIC

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

النمط 2

الإصدار 1 من 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() التي يتم إنشاؤها في رمز المصدر الإصدار 2 من GAPIC معلَمتَين فقط ($customerId و$query) لأنهما تتطلّبان مَعلمتَين. لطلب إجمالي عدد النتائج المطابقة مع طلب البحث مع تجاهل عبارة LIMIT، عليك ضبطها بشكلٍ صريح باستخدام السمة setReturnTotalResultsCount(). وبدلاً من ذلك، يمكنك تمرير جميع المعلمات معًا مع الدالة الإنشائية SearchGoogleAdsRequest، كما هو موضح في النمط 3.

النمط 1

الإصدار 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

الإصدار 1 من GAPIC

N/A

الإصدار 2 من GAPIC

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

النمط 3

الإصدار 1 من 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() في رمز المصدر من الإصدار 2 من GAPIC في هذه الحالة، وعليك في هذه الحالة إنشاء كائن الطلب بنفسك.

النمط 1

الإصدار 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

الإصدار 1 من GAPIC

N/A

الإصدار 2 من GAPIC

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