זמן קצוב לתפוגה

לכל השירותים של Google Ads API יש הגדרות ברירת מחדל, כולל זמני קצובות לתפוגה, שמשמשות את התעבורה. לכל שירות של גרסה מסוימת של Google Ads API יש קובץ JSON ייעודי עם הגדרות ברירת המחדל האלה, שמוגדרות ברמות השירות והשיטה. לדוגמה, ב-GitHub אפשר למצוא את קובצי ההגדרות של משאבי השירות לגרסה העדכנית של Google Ads API.

הגדרות ברירת המחדל מתאימות לרוב תרחישי השימוש, אבל יכול להיות שיהיו מקרים שבהם תצטרכו לשנות אותן. ספריית הלקוח של PHP תומכת בשינוי הגדרות הזמן הקצוב לתפוגה לכל קריאה (שמצוינות באלפיות השנייה באמצעות האפשרות timeoutMillis) גם לסטרימינג בשרת וגם לקריאות אונריות.

אפשר להגדיר ערכי זמן קצוב לתפוגה גבוהים (כמו שעתיים או יותר) בספריית הלקוח, אבל שרתי proxy בסיסיים של הרשת או שרת ה-API עדיין יכולים לסיים בקשות ארוכות מוקדם יותר ולהחזיר שגיאת סטטוס DEADLINE_EXCEEDED.

שינוי של הזמן הקצוב לתפוגה של קריאה לסטרימינג בשרת

שיטת השירות היחידה של Google Ads API שמשתמשת בקריאת סטרימינג של שרת היא GoogleAdsService.SearchStream. כדי לשנות את הזמן הקצוב לתפוגה שמוגדר כברירת מחדל, מעבירים את הערך timeoutMillis (באלפיות השנייה) במערך האפשרויות האופציונליות של הקריאה כשמפעילים את השיטה:

    private static function makeServerStreamingCall(
        GoogleAdsClient $googleAdsClient,
        int $customerId
    ) {
        $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
        // Creates a query that retrieves all campaign IDs.
        $query = 'SELECT campaign.id FROM campaign';

        $output = '';
        try {
            // Issues a search stream request by setting a custom client timeout.
            /**
 * @var GoogleAdsServerStreamDecorator $stream
*/
            $stream = $googleAdsServiceClient->searchStream(
                SearchGoogleAdsStreamRequest::build($customerId, $query),
                [
                    // Any server streaming call has a default timeout setting. For this
                    // particular call, the default setting can be found in the following file:
                    // https://github.com/googleads/google-ads-php/blob/master/src/Google/Ads/GoogleAds/V26/Services/resources/google_ads_service_client_config.json.
                    //
                    // When making a server streaming call, an optional argument is provided and can
                    // be used to override the default timeout setting with a given value.
                    'timeoutMillis' => self::CLIENT_TIMEOUT_MILLIS
                ]
            );
            // Iterates over all rows in all messages and collects the campaign IDs.
            foreach ($stream->iterateAllElements() as $googleAdsRow) {
                /**
 * @var GoogleAdsRow $googleAdsRow
*/
                $output .= ' ' . $googleAdsRow->getCampaign()->getId();
            }
            print 'The server streaming call completed before the timeout.' . PHP_EOL;
        } catch (ApiException $exception) {
            if ($exception->getStatus() === ApiStatus::DEADLINE_EXCEEDED) {
                print 'The server streaming call did not complete before the timeout.' . PHP_EOL;
            } else {
                // Bubbles up if the exception is not about timeout.
                throw $exception;
            }
        } finally {
            print 'All campaign IDs retrieved:' . ($output ?: ' None') . PHP_EOL;
        }
    }

ביטול הגדרות הזמן הקצוב לתפוגה עבור שיחה אוניטרית

רוב השיטות של שירות Google Ads API משתמשות בקריאות Unary. דוגמאות אופייניות הן GoogleAdsService.Search ו-GoogleAdsService.Mutate. כדי לשנות את הזמן הקצוב לתפוגה שמוגדר כברירת מחדל, מעבירים את timeoutMillis (באלפיות השנייה) במערך האפשרויות של השיחה (אופציונלי) כשמפעילים את השיטה:

    private static function makeUnaryCall(GoogleAdsClient $googleAdsClient, int $customerId)
    {
        $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
        // Creates a query that retrieves all campaign IDs.
        $query = 'SELECT campaign.id FROM campaign';

        $output = '';
        try {
            // Issues a search request by setting a custom client timeout.
            $response = $googleAdsServiceClient->search(
                SearchGoogleAdsRequest::build($customerId, $query),
                [
                    // Any unary call is retryable and has default retry settings.
                    // Complete information about these settings can be found here:
                    // https://googleapis.github.io/gax-php/master/Google/ApiCore/RetrySettings.html.
                    // For this particular call, the default retry settings can be found in the
                    // following file:
                    // https://github.com/googleads/google-ads-php/blob/master/src/Google/Ads/GoogleAds/V26/Services/resources/google_ads_service_client_config.json.
                    //
                    // When making an unary call, an optional argument is provided and can be
                    // used to override the default retry settings with given values.
                    'retrySettings' => [
                        // Sets the maximum accumulative timeout of the call, it includes all tries.
                        'totalTimeoutMillis' => self::CLIENT_TIMEOUT_MILLIS,
                        // Sets the timeout that is used for the first try to one tenth of the
                        // maximum accumulative timeout of the call.
                        // Note: This overrides the default value and can lead to
                        // RequestError.RPC_DEADLINE_TOO_SHORT errors when too small. We recommend
                        // to do it only if necessary.
                        'initialRpcTimeoutMillis' => self::CLIENT_TIMEOUT_MILLIS / 10,
                        // Sets the maximum timeout that can be used for any given try to one fifth
                        // of the maximum accumulative timeout of the call (two times greater than
                        // the timeout that is used for the first try).
                        'maxRpcTimeoutMillis' => self::CLIENT_TIMEOUT_MILLIS / 5
                    ]
                ]
            );
            // Iterates over all rows in all messages and collects the campaign IDs.
            foreach ($response->iterateAllElements() as $googleAdsRow) {
                /**
 * @var GoogleAdsRow $googleAdsRow
*/
                $output .= ' ' . $googleAdsRow->getCampaign()->getId();
            }
            print 'The unary call completed before the timeout.' . PHP_EOL;
        } catch (ApiException $exception) {
            if ($exception->getStatus() === ApiStatus::DEADLINE_EXCEEDED) {
                print 'The unary call did not complete before the timeout.' . PHP_EOL;
            } else {
                // Bubbles up if the exception is not about timeout.
                throw $exception;
            }
        } finally {
            print 'All campaign IDs retrieved:' . ($output ?: ' None') . PHP_EOL;
        }
    }