Protocole GAPIC

Le code source figurant dans le répertoire src/Google/Ads/GoogleAds/vX de la bibliothèque cliente PHP de l'API Google Ads, où X correspond à la version de l'API Google Ads, est automatiquement généré à l'aide du générateur GAPIC (Generated API Client), en fonction des fichiers proto publiés.

Le code source généré est ensuite modifié pour contenir des références aux caractéristiques et aux classes requises pour créer les clients de service qui fonctionnent avec l'API Google Ads à l'aide de la classe GoogleAdsClient, créée en appelant GoogleAdsClientBuilder::build(). GoogleAdsClient et GoogleAdsClientBuilder sont des classes créées manuellement qui se trouvent dans src/Google/Ads/GoogleAds/Lib/vX/.

Code source de GAPIC v2

Depuis la version v20.1.0, la bibliothèque cliente inclut également une nouvelle version du code source GAPIC dans src/Google/Ads/GoogleAds/vX, qui permet de transmettre un objet de requête aux méthodes des clients de service. Cette nouvelle version, appelée GAPIC v2, permet également de préparer les futures fonctionnalités. L'ancien code source de GAPIC, GAPIC v1, est toujours généré et inclus dans chaque version jusqu'à la fin de l'année 2023.

La bibliothèque cliente PHP de l'API Google Ads vous permet de sélectionner la version à associer à GoogleAdsClient à l'aide du paramètre de configuration useGapicV2Source. Lorsque ce paramètre est défini sur true, la bibliothèque cliente génère un objet GoogleAdsClient qui crée les clients de service GAPIC v2.

Lieux de cours générés

Voici les différences d'emplacement de fichiers entre les versions GAPIC pour les deux types de classes:

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

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

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

Utilisation

GAPIC v1 nécessite de transmettre chaque paramètre de requête directement à une méthode, tandis que GAPIC v2 nécessite de transmettre un objet de requête à la place. Notez que dans certains cas, il existe plusieurs façons de créer un objet de requête, car GAPIC v2 génère également une méthode pratique nommée build() pour transmettre les paramètres obligatoires.

Exemple 1.1: Méthodes avec les paramètres obligatoires

L'exemple de code suivant compare l'appel de CampaignService::mutate() dans GAPIC v1 et v2. Notez que tous les paramètres ($customerId et $operations) sont obligatoires. Par conséquent, la propriété build() qui accepte les deux paramètres est générée dans le code GAPIC v2.

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

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

N/A

$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$request = (new MutateCampaignsRequest())
    ->setCustomerId($customerId)
    ->setCampaignOperations($campaignOperations);
$response = $campaignServiceClient->mutateCampaigns($request);
      

Exemple 1.2: Méthodes avec les paramètres obligatoires et facultatifs

L'exemple de code suivant compare l'appel de GoogleAdsServiceClient::search() dans GAPIC v1 et v2. Dans cet exemple, le build() généré dans le code source GAPIC v2 n'accepte que deux paramètres ($customerId et $query), car ce sont des paramètres obligatoires. Pour définir une taille de page, qui est un paramètre facultatif, vous devez la définir explicitement à l'aide de setPageSize(). Vous pouvez également transmettre tous les paramètres au constructeur de SearchGoogleAdsRequest, comme illustré dans le modèle 3.

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['pageSize' => self::PAGE_SIZE]
);
      

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setPageSize(self::PAGE_SIZE)
);
      

N/A

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setPageSize(self::PAGE_SIZE);
$response = $googleAdsServiceClient->search($request);
      

N/A

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'page_size' => self::PAGE_SIZE
]);
$response = $googleAdsServiceClient->search($request);
      

Exemple 2: Méthodes avec uniquement des paramètres facultatifs

Comparez les appels de GeoTargetConstantServiceClient::suggestGeoTargetConstants() dans GAPIC v1 et v2. Étant donné que tous les paramètres de GeoTargetConstantServiceClient::suggestGeoTargetConstants() sont facultatifs, build() n'est pas généré dans le code source de GAPIC v2 dans ce cas. Vous devez créer vous-même l'objet de requête.

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

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$request = (new SuggestGeoTargetConstantsRequest())
    ->setLocale($locale)
    ->setCountryCode($countryCode)
    ->setLocationNames(new LocationNames(['names' => $locationNames]));
$response =
    $geoTargetConstantServiceClient->suggestGeoTargetConstants($request);
      

N/A

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