GAPIC

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

Il codice sorgente generato viene quindi modificato per contenere i riferimenti ai trait e alle classi necessari per creare i client di servizio che funzionano con l'API Google Ads utilizzando la classe GoogleAdsClient, creata chiamando GoogleAdsClientBuilder::build(). Sia GoogleAdsClient che GoogleAdsClientBuilder sono corsi creati manualmente che si trovano 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 del servizio. Questa nuova versione, denominata GAPIC v2, serve anche a preparare nuove funzionalità in futuro. 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 consente di selezionare la versione da collegare a GoogleAdsClient utilizzando l'impostazione di configurazione useGapicV2Source. Se questa impostazione è impostata su true, la libreria client genera un oggetto GoogleAdsClient che crea i client di servizio GAPIC v2.

Sedi dei corsi generate

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

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.
Clienti post-elaborati GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

Utilizzo

GAPIC v1 richiede di passare ciascun parametro di richiesta direttamente a un metodo, mentre GAPIC v2 richiede invece di passare un oggetto di richiesta. Tieni presente che, in alcuni casi, hai più di un modo per creare un oggetto di richiesta poiché GAPIC v2 genera anche un pratico metodo denominato build() per il passaggio dei parametri obbligatori.

Esempio 1.1: metodi con i parametri richiesti

Il codice di esempio seguente confronta le chiamate a CampaignService::mutate() in GAPIC v1 e v2. Tieni presente che tutti i parametri ($customerId e $operations) sono parametri obbligatori, pertanto il valore 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
    )
);
Motivo 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 i parametri obbligatori e i parametri facoltativi

Il seguente codice di esempio confronta le chiamate a GoogleAdsServiceClient::search() in GAPIC v1 e v2. In questo esempio, l'elemento build() generato nel codice sorgente GAPIC v2 accetta solo due parametri ($customerId e $query) perché sono parametri obbligatori. Per impostare una dimensione di pagina, che è un parametro facoltativo, devi impostarla esplicitamente 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)
);
Motivo 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);
Motivo 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 la chiamata 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 GAPIC v2. Devi creare l'oggetto richiesta manualmente.

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