PHP

Google 提供 PHP 用戶端程式庫，可與 Ad Manager API 互動。 建議使用 Composer 搭配用戶端程式庫。

如要開始使用，請在所選 IDE 中建立新專案，或將依附元件新增至現有專案。Google 會將用戶端程式庫構件發布至 Packagist，名稱為 googleads/ad-manager。

composer.json 

"require": {
  "googleads/ad-manager": "^0.14.0"
}

指令列

composer require googleads/ad-manager

設定憑證

PHP 用戶端程式庫會使用 OAuth2 和應用程式預設憑證 (ADC) 進行驗證。

ADC 會依序在下列位置搜尋憑證：

  1. GOOGLE_APPLICATION_CREDENTIALS 環境變數。
  2. 透過 Google Cloud CLI (gcloud CLI) 設定的使用者憑證。
  3. 在 Google Cloud 上執行時，附加至 Google Cloud 資源的服務帳戶。

如要建立及設定 ADC 憑證，請參閱「驗證」。

發出第一項要求

每項服務都有 ServiceClient 物件，其中包含每個 REST 方法的方法。以下範例會讀取 Network 物件。

<?php

use Google\Ads\AdManager\V1\Client\NetworkServiceClient;
use Google\Ads\AdManager\V1\GetNetworkRequest;
use Google\Ads\AdManager\V1\Network;
use Google\ApiCore\ApiException;

/**
 * Retrieves a `Network` object.
 *
 * @param string $formattedName Resource name of Network.
 *                              Format: networks/{network_code}
 *                              Please see {@see NetworkServiceClient::networkName()} for help formatting this field.
 */
function get_network_sample(string $formattedName): void
{
    // Create a client.
    $networkServiceClient = new NetworkServiceClient();

    // Prepare the request message.
    $request = (new GetNetworkRequest())
        ->setName($formattedName);

    // Call the API and handle any network failures.
    try {
        /** @var Network $response */
        $response = $networkServiceClient->getNetwork($request);
        printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 */
function callSample(): void
{
    $formattedName = NetworkServiceClient::networkName('NETWORK_CODE');

    get_network_sample($formattedName);
}

如需其他方法和資源的範例，請參閱 GitHub 存放區 googleapis/php-ads-ad-manager。

記錄 HTTP 要求和回應

PHP 用戶端程式庫支援符合 PSR-3 的記錄器，可記錄 HTTP 要求和回應。記錄功能預設為停用。

如要啟用預設記錄到標準輸出，請在 PHP 程式碼或環境中，將環境變數 GOOGLE_SDK_PHP_LOGGING 設為 true：

putenv('GOOGLE_SDK_PHP_LOGGING=true');

$client = new NetworkServiceClient();
 
export GOOGLE_SDK_PHP_LOGGING=true

或者，您也可以在建構服務用戶端時，傳遞任何符合 PSR-3 的記錄器：

use Monolog\Handler\StreamHandler;
use Monolog\Level;
use Monolog\Logger;

$monologLogger = new Logger('sdk client');
$monologLogger->pushHandler(new StreamHandler('php://stdout', Level::Debug));

$client = new NetworkServiceClient([
    'logger' => $monologLogger
]);

處理錯誤

在 PHP 用戶端程式庫中，所有 Ad Manager API 錯誤都會擲回 ApiException 類型的例外狀況：

剖析錯誤

錯誤原因欄位會明確指出錯誤類型。使用這個欄位決定如何處理錯誤。

try {
    $response = $networkServiceClient->getNetwork($formattedName);
    printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
} catch (ApiException $ex) {
    printf('Error message: %s' . PHP_EOL, $ex->getBasicMessage());
    printf('Reason: %s' . PHP_EOL, $ex->getReason());
}

Ad Manager API 錯誤也包含專屬的 request_id，您可以提供給支援團隊，協助排解問題。以下範例會擷取 request_id。

$requestInfo = null;
foreach ($ex->getMetadata() as $metadata) {
    if($metadata["@type"] === "type.googleapis.com/google.rpc.RequestInfo") {
        $requestInfo = $metadata;
        break;
    }
}
if ($requestInfo == null) {
    printf('Unexpected empty RequestInfo');
} else {
    printf('RequestId: %s' . PHP_EOL, $requestInfo['requestId']);
}

建構資源名稱

用戶端程式庫提供輔助類別，可從 ID 建構資源名稱。

use Google\Ads\AdManager\V1\Client\OrderServiceClient;

//  Constructs a String in the format:
//  "networks/{networkCode}/orders/{orderId}"
$orderName = OrderServiceClient::orderName("NETWORK_CODE", "ORDER_ID");

指定 Proxy 設定

PHP 用戶端程式庫會遵守 HTTP_PROXY 和 HTTPS_PROXY 環境設定。