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

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

بعد ذلك، يتم تعديل رمز المصدر الذي تم إنشاؤه ليحتوي على إشارات إلى السمات والklassen المطلوبة لإنشاء عملاء الخدمة الذين يعملون مع Google Ads API باستخدام GoogleAdsClient class، والتي يتم إنشاؤها من خلال memanggilGoogleAdsClientBuilder::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(). بما أنّ جميع paramter في 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])
    ])
);