Protocole GAPIC

Le code source dans le répertoire src/Google/Ads/GoogleAds/vX de la bibliothèque cliente PHP de l'API Google Ads, où X est 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 fonctionnant 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 et situées dans src/Google/Ads/GoogleAds/Lib/vX/.

Code source 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, prépare également l'avenir de nouvelles fonctionnalités. L'ancien code source 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 des clients de service GAPIC v2.

Emplacements de cours générés

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

Clients générés par GAPIC et fichiers associés GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2: aucune. Seul un fichier post-traité est généré.
Clients post-traités GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

Utilisation

GAPIC v1 nécessite que vous transmettiez chaque paramètre de requête directement à une méthode, tandis que GAPIC v2 nécessite que vous transmettiez un objet de requête à la place. Notez que dans certains cas, vous pouvez créer un objet de requête de plusieurs façons, 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 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, le build() qui accepte les deux paramètres est généré dans le code GAPIC v2.

Modèle 1 GAPIC v1 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    $customerId,
    $campaignOperations
);
GAPIC v2 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build(
      $customerId,
      $campaignOperations
    )
);
Modèle 2 GAPIC v1 
N/A
GAPIC v2 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$request = (new MutateCampaignsRequest())
    ->setCustomerId($customerId)
    ->setCampaignOperations($campaignOperations);
$response = $campaignServiceClient->mutateCampaigns($request);

Exemple 1.2: Méthodes avec paramètres obligatoires et paramètres 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 demander le nombre total de résultats correspondant à la requête en ignorant la clause LIMIT, vous devez le définir explicitement à l'aide de setReturnTotalResultsCount(). Vous pouvez également transmettre tous les paramètres ensemble au constructeur de SearchGoogleAdsRequest, comme indiqué dans le modèle 3.

Modèle 1 GAPIC v1 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['returnTotalResultsCount' => true]
);
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setReturnTotalResultsCount(true)
);
Modèle 2 GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setReturnTotalResultsCount(true);
$response = $googleAdsServiceClient->search($request);
Modèle 3 GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'return_total_results_count' => true
]);
$response = $googleAdsServiceClient->search($request);

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

Comparez l'appel 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 GAPIC v2 dans ce cas. Vous devez créer l'objet de requête vous-même.

Modèle 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);
Modèle 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])
    ])
);