Protocole GAPIC

Le code source dans src/Google/Ads/GoogleAds/vX Répertoire de la bibliothèque cliente PHP de l'API Google Ads, où X correspond à l'API Google Ads est générée automatiquement à l'aide du client GAPIC (Generated API Client) Générateur, basé sur la version publiée fichier .proto fichiers.

Le code source généré est ensuite modifié pour contenir des références à des caractéristiques et nécessaires 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 Les GoogleAdsClientBuilder sont des classes créées manuellement 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 au service des clients méthodes. Cette nouvelle version, appelée GAPIC v2, sert également de préparation de nouvelles fonctionnalités à l'avenir. L'ancien code source GAPIC, GAPIC v1, est toujours générés 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 Clients de service GAPIC v2.

Emplacements de cours générés

Voici les différences d'emplacement de fichier 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: aucun. 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

Avec GAPIC v1, vous devez transmettre 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 Dans certains cas, vous disposez de plusieurs méthodes pour créer un objet de requête depuis GAPIC. La version 2 génère également une méthode pratique nommée build() pour transmettre la valeur required paramètres.

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 paramètres 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 GAPIC Le code source de la version 2 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 la définir explicitement en utilisant setReturnTotalResultsCount() Vous pouvez aussi transmettre tous les paramètres 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

Comparer les appels passés à GeoTargetConstantServiceClient::suggestGeoTargetConstants() dans GAPIC v1 et v2. Étant donné que tous les paramètres Les GeoTargetConstantServiceClient::suggestGeoTargetConstants() sont facultatifs, Dans ce cas, build() n'est pas généré dans le code source GAPIC v2. 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])
    ])
);