GAPIC

Il codice sorgente nella directory src/Google/Ads/GoogleAds/vX della libreria client PHP dell'API Google Ads, dove X è la versione dell'API Google Ads, viene generato automaticamente utilizzando il generatore di GAPIC (client API generato), in base ai file di protocollo pubblicati.

Il codice sorgente generato viene poi modificato in modo da contenere i riferimenti a trait e classi necessari per creare i client di servizi che funzionano con l'API Google Ads tramite la classe GoogleAdsClient, creata chiamando GoogleAdsClientBuilder::build(). Sia GoogleAdsClient sia GoogleAdsClientBuilder sono corsi creati manualmente e situati in src/Google/Ads/GoogleAds/Lib/vX/.

Codice sorgente GAPIC v2

Dalla versione v20.1.0, la libreria client include anche una nuova versione del codice sorgente GAPIC in src/Google/Ads/GoogleAds/vX che supporta il passaggio di un oggetto di richiesta ai metodi dei client di servizio. La nuova versione, chiamata GAPIC v2, serve anche per preparare le nuove funzionalità future. Il codice sorgente GAPIC precedente, GAPIC v1, viene ancora generato e incluso in ogni release fino alla fine del 2023.

La libreria client PHP dell'API Google Ads ti consente di selezionare la versione da collegare a GoogleAdsClient utilizzando l'impostazione di configurazione useGapicV2Source. Se questa impostazione viene impostata su true, la libreria client genera un oggetto GoogleAdsClient che crea i client di servizio GAPIC v2.

Sedi generate dal corso

Ecco le differenze nelle posizioni dei file tra le versioni GAPIC per i due tipi di classe:

Client generati da GAPIC e file correlati GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2: nessuno. Viene generato solo un file post-elaborato.
Client post-elaborati GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

Utilizzo

GAPIC v1 richiede il passaggio di ogni parametro di richiesta direttamente a un metodo, mentre GAPIC v2 richiede il passaggio di un oggetto di richiesta. Tieni presente che, in alcuni casi, esistono più modi per creare un oggetto di richiesta, dato che GAPIC v2 genera anche un pratico metodo denominato build() per passare i parametri obbligatori.

Esempio 1.1: metodi con parametri obbligatori

Il codice campione seguente confronta le chiamate a CampaignService::mutate() in GAPIC v1 e v2. Tieni presente che tutti i parametri ($customerId e $operations) sono obbligatori, pertanto il build() che accetta entrambi i parametri viene generato nel codice GAPIC v2.

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

Esempio 1.2: metodi con parametri obbligatori e facoltativi

Il codice campione seguente confronta le chiamate a GoogleAdsServiceClient::search() nelle versioni 1 e 2 di GAPIC. In questo esempio, il valore build() generato nel codice sorgente di GAPIC v2 accetta solo due parametri ($customerId e $query) perché sono parametri obbligatori. Per impostare la dimensione della pagina, parametro facoltativo, devi impostarla in modo esplicito utilizzando setPageSize(). In alternativa, puoi passare tutti i parametri insieme al costruttore di SearchGoogleAdsRequest, come mostrato nel pattern 3.

Schema 1 GAPIC v1 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['pageSize' => self::PAGE_SIZE]
);
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setPageSize(self::PAGE_SIZE)
);
Schema 2 GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setPageSize(self::PAGE_SIZE);
$response = $googleAdsServiceClient->search($request);
Schema 3 GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'page_size' => self::PAGE_SIZE
]);
$response = $googleAdsServiceClient->search($request);

Esempio 2: metodi con solo parametri facoltativi

Confronta le chiamate a GeoTargetConstantServiceClient::suggestGeoTargetConstants() in GAPIC v1 e v2. Poiché tutti i parametri di GeoTargetConstantServiceClient::suggestGeoTargetConstants() sono facoltativi, in questo caso build() non viene generato nel codice sorgente di GAPIC v2, ma devi creare personalmente l'oggetto di richiesta.

Schema 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);
Schema 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])
    ])
);