가교

Google Ads API PHP 클라이언트 라이브러리의 src/Google/Ads/GoogleAds/vX 디렉터리(여기서 X는 Google Ads API 버전)에 있는 소스 코드는 게시된 proto 파일을 기반으로 GAPIC(생성된 API 클라이언트) 생성기를 사용하여 자동으로 생성됩니다.

생성된 소스 코드는 GoogleAdsClientBuilder::build()를 호출하여 만든 GoogleAdsClient 클래스를 사용하여 Google Ads API로 작동하는 서비스 클라이언트를 만드는 데 필요한 트레잇 및 클래스에 대한 참조를 포함하도록 수정됩니다. GoogleAdsClient와 GoogleAdsClientBuilder는 모두 src/Google/Ads/GoogleAds/Lib/vX/에 있는 수동으로 생성된 클래스입니다.

GAPIC v2 소스 코드

버전 v20.1.0부터 클라이언트 라이브러리에는 서비스 클라이언트의 메서드에 요청 객체를 전달하는 것을 지원하는 새로운 버전의 GAPIC 소스 코드도 src/Google/Ads/GoogleAds/vX에 포함됩니다. GAPIC v2라고 하는 이 새 버전은 향후 새로운 기능을 위한 준비 역할도 합니다. 이전 GAPIC 소스 코드인 GAPIC v1은 계속 생성되며 2023년 말까지 각 버전에 포함됩니다.

Google Ads API PHP 클라이언트 라이브러리를 사용하면 구성 설정 useGapicV2Source를 사용하여 GoogleAdsClient에 연결할 버전을 선택할 수 있습니다. 이 설정을 true로 설정하면 클라이언트 라이브러리는 GAPIC v2 서비스 클라이언트를 만드는 GoogleAdsClient 객체를 생성합니다.

생성된 수업 위치

두 클래스 유형에서 GAPIC 버전 간 파일 위치의 차이점은 다음과 같습니다.

GAPIC에서 생성한 클라이언트 및 관련 파일 GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2: 없음 후처리된 파일만 생성됩니다.
후처리 클라이언트 GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

사용

GAPIC v1에서는 각 요청 매개변수를 메서드에 직접 전달해야 하지만 GAPIC v2에서는 요청 객체를 대신 전달해야 합니다. GAPIC v2에서는 필수 매개변수를 전달하기 위한 build()이라는 편리한 메서드를 생성하므로 요청 객체를 만드는 방법이 여러 개 있는 경우도 있습니다.

예시 1.1: 필수 매개변수가 있는 메서드

다음 샘플 코드는 GAPIC v1과 v2에서의 CampaignService::mutate() 호출을 비교합니다. 모든 매개변수 ($customerId 및 $operations)는 필수 매개변수이므로 두 매개변수를 모두 허용하는 build()가 GAPIC v2 코드에 생성됩니다.

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

예시 1.2: 필수 매개변수와 선택적 매개변수가 있는 메서드

다음 샘플 코드는 GAPIC v1과 v2에서의 GoogleAdsServiceClient::search() 호출을 비교합니다. 이 예에서 GAPIC v2 소스 코드에서 생성된 build()는 필수 매개변수이므로 두 개의 매개변수 ($customerId 및 $query)만 허용합니다. 선택적 매개변수인 페이지 크기를 설정하려면 setPageSize()를 사용하여 명시적으로 설정해야 합니다. 또는 패턴 3과 같이 SearchGoogleAdsRequest의 생성자에 모든 매개변수를 함께 전달할 수 있습니다.

패턴 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)
);
패턴 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);
패턴 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);

예시 2: 선택적 매개변수만 있는 메서드

GAPIC v1과 v2에서의 GeoTargetConstantServiceClient::suggestGeoTargetConstants() 호출을 비교해 보세요. GeoTargetConstantServiceClient::suggestGeoTargetConstants()의 모든 매개변수는 선택사항이므로 이 경우에는 GAPIC v2 소스 코드에서 build()이 생성되지 않습니다. 사용자가 직접 요청 객체를 만들어야 합니다.

패턴 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);
패턴 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])
    ])
);