پیکربندی

کتابخانه کارخواه Google Ads API PHP چندین تنظیم پیکربندی ارائه می‌دهد که می‌توانید از آن‌ها برای سفارشی‌سازی رفتار کتابخانه استفاده کنید.

توجه: تنظیمات پویای صریحاً مشخص‌شده تنظیمات بارشده از متغیرهای محیطی یا فایل‌های پیکربندی INI را بسته به ترتیبی که روش‌های سازنده فراخوانی می‌شوند لغو می‌کنند.

فایل پیکربندی

می‌توانید اکثر این تنظیمات پیکربندی را در فایل‌های پیکربندی INI ذخیره کنید و هنگام نمونه‌سازی مشتریان از آن‌ها استفاده کنید، برای مثال، google_ads_php.ini.

سازندگان اعتبارنامه و کارخواه هر دو روش‌های fromFile را برای بار کردن تنظیمات از چنین فایل‌هایی ارائه می‌دهند:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

اگر مسیر پیکربندی به‌عنوان آرگومان ارائه نشده باشد، روش‌های fromFile از مسیر پیکربندی پیش‌فرض بار می‌شود که عبارت است از:

1. مقدار متغیر محیطی به‌نام GOOGLE_ADS_CONFIGURATION_FILE_PATH درصورت تنظیم.
2. درغیراین‌صورت، فایل google_ads_php.ini در دایرکتوری HOME.

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

پیکربندی پویا

می‌توانید این تنظیمات پیکربندی را به‌صورت پویا هنگام نمونه‌سازی مشتریان تنظیم کنید:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

متغیرهای محیط پیکربندی

می‌توانید برخی‌از تنظیمات پیکربندی را از متغیرهای محیطی هنگام نمونه‌سازی مشتریان تنظیم کنید (متغیرهای محیطی استاندارد را ببینید).

سازندگان اعتبارنامه و کارخواه هر دو روش‌های fromEnvironmentVariables را برای بار کردن تنظیمات از متغیرهای محیطی ارائه می‌دهند.

توجه: متغیرهای محیطی تنظیم‌نشده درنظر گرفته نمی‌شوند.

$oAuth2Credential = (new OAuth2TokenBuilder())
    // ...
    ->fromEnvironmentVariables()
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    // ...
    ->fromEnvironmentVariables()
    ->build();

فیلدهای پیکربندی

توجه: فیلدهای grpcChannelCredential،‏ unaryMiddlewares، streamingMiddlewares، و grpcInterceptors را نمی‌توان از فایل یا رشته پیکربندی تنظیم کرد و فقط می‌توان آن‌ها را به‌صورت پویا پیکربندی کرد.

تنظیمات پیکربندی از چندین فیلد پشتیبانی می‌کند که در دسته‌هایی سازمان‌دهی شده‌اند:

1. فیلدهای استفاده‌شده توسط OAuth2TokenBuilder:
   • حالت برنامه:
     • [OAUTH2] clientId: شناسه کارخواه OAuth2 شما.
     • [OAUTH2] clientSecret: رمز کارخواه OAuth2 شما.
     • [OAUTH2] refreshToken: کد بازآوری OAuth2 شما.
   • حالت حساب سرویس:
     • [OAUTH2] jsonKeyFilePath: مسیر کلید JSON.
     • [OAUTH2] scopes: گستره‌های OAuth2 (به‌طور پیش‌فرض https://www.googleapis.com/auth/adwords در v32.1.0 و نسخه‌های جدیدتر؛ در نسخه‌های قدیمی‌تر از v32.1.0 یا هنگام استفاده از گستره‌های سفارشی الزامی است؛ توسط fromEnvironmentVariables() از متغیر محیطی خوانده نمی‌شود).
     • [OAUTH2] impersonatedEmail: نشانی ایمیل اختیاری برای جعل هویت هنگام استفاده از واگذاری در سطح دامنه Google Workspace.
   • حالت «اطلاعات اعتباری پیش‌فرض برنامه»:
     • وقتی هیچ‌کدام از فیلدهای «حالت برنامه» یا «حالت حساب سرویس» تنظیم نشده باشند، OAuth2TokenBuilder به‌طور خودکار به «اطلاعات کاربری پیش‌فرض برنامه» (ADC) برمی‌گردد.
2. فیلدهای استفاده‌شده توسط GoogleAdsClientBuilder:
   • [GOOGLE_ADS] loginCustomerId: شناسه مشتری مجاز برای استفاده در درخواست.
   • ‫[GOOGLE_ADS] linkedCustomerId: شناسه مشتری پیوندشده.
   • [GOOGLE_ADS] endpoint: نقطه پایانی سرور Google Ads API جایگزین اختیاری.
   • [LOGGING] logFilePath: مسیر خروجی ثبت گزارش.
   • ‫[LOGGING] logLevel: سطح ثبت گزارش.
   • ‫[CONNECTION] proxy: نشانی وب پراکسی سرور استفاده‌شده برای اتصال اینترنت.
   • ‫[CONNECTION] transport: انتقال شبکه (grpc یا rest).
   • [CONNECTION] grpcChannelIsSecure: آیا کانال gRPC امن است.
   • ‫[CONNECTION] grpcChannelCredential: اطلاعات اعتباری کانال gRPC.
   • ‫[CONNECTION] unaryMiddlewares: میان‌افزارهای تک‌عضوی.
   • ‫[CONNECTION] streamingMiddlewares: میان‌افزارهای جاری‌سازی.
   • ‫[CONNECTION] grpcInterceptors: رهگیرهای gRPC.

اعتبارسنجی پیکربندی

تنظیمات پیکربندی هنگام نمونه‌سازی کارخواه‌ها بررسی می‌شود و درصورت نامعتبر بودن، استثناهایی ایجاد می‌شود. قوانین اعتبارسنجی به شرح زیر است:

1. [OAUTH2] فیلدها نباید هم‌زمان برای هر دو حالت «برنامه» و «حساب سرویس» تنظیم شوند.
2. [OAUTH2] jsonKeyFilePath باید هنگام استفاده از حالت حساب «سرویس» تنظیم شود (در نسخه‌های قبل‌از v32.1.0، [OAUTH2] scopes نیز باید تنظیم شود؛ در v32.1.0 و نسخه‌های جدیدتر، scopes به‌طور پیش‌فرض روی https://www.googleapis.com/auth/adwords تنظیم می‌شود).
3. ‫[OAUTH2] clientId، [OAUTH2] clientSecret، و [OAUTH2] refreshToken باید هنگام استفاده از حالت «برنامه» تنظیم شوند.
4. درصورت تنظیم، [GOOGLE_ADS] loginCustomerId و [GOOGLE_ADS] linkedCustomerId باید اعداد مثبت باشند.
5. اگر تنظیم شده باشد، [CONNECTION] proxy باید نشانی وب معتبری باشد (به فیلتر FILTER_VALIDATE_URL مراجعه کنید).
6. اگر تنظیم شده باشد، [LOGGING] logLevel باید سطح گزارش PSR معتبری با حروف بزرگ باشد، مثل INFO.
7. اگر تنظیم شده باشد، [CONNECTION] transport باید grpc یا rest باشد.
8. اگر [CONNECTION] transport روی grpc تنظیم شده باشد، انتقال gRPC باید توسط محیط پشتیبانی شود (به راهنمای انتقال مراجعه کنید).
9. وقتی [CONNECTION] transport روی grpc تنظیم نشده باشد، [CONNECTION] grpcChannelIsSecure باید true باشد (اتصال‌های REST همیشه به HTTPS نیاز دارند).
10. [CONNECTION] grpcChannelCredential را فقط زمانی می‌توان تنظیم کرد که [CONNECTION] transport روی grpc تنظیم شده باشد.
11. [CONNECTION] grpcChannelCredential فقط زمانی می‌تواند تنظیم شود که [CONNECTION] grpcChannelIsSecure روی true باشد.