کتابخانه مشتری .NET

کتابخانه مشتری .NET در GitHub میزبانی می‌شود و به‌عنوان بسته NuGet توزیع می‌شود. این کتابخانه چندین ویژگی برای کمک به شما در استفاده از میانای برنامه‌سازی کاربردی ارائه می‌دهد، ازجمله مدیریت آسان‌تر اطلاعات اعتباری و ایجاد کارخواه‌های سرویس Google Ads API.

این کتابخانه از چارچوب‌های .NET زیر پشتیبانی می‌کند:

  • ‫.NET Framework نسخه ۴.۷.۲ و بالاتر (net472)
  • ‫.NET Standard 2.1‏ (netstandard2.1)
  • .NET 8.0 (net8.0)

‫NET Standard 2.1 با چندین نسخه و پیاده‌سازی دیگر .NET سازگار است، بنابراین کتابخانه ممکن است در بسیاری از پلاتفرم‌های دیگر به‌خوبی کار کند. بااین‌حال، ما سازگاری را به‌طور رسمی آزمایش نکرده‌ایم و بنابراین به‌طور رسمی از این پلاتفرم‌ها پشتیبانی نمی‌کنیم. برای کسب اطلاعات بیشتر، سند NET Standard 2.1. را ببینید.

کتابخانه Google Ads API .NET از Grpc.Net.Client به‌عنوان لایه انتقال پیش‌فرض استفاده می‌کند، و در پلاتفرم‌های پشتیبانی‌نشده به Grpc.Core برمی‌گردد. درحالی‌که می‌توانید با تنظیم UseGrpcCore روی true، استفاده از Grpc.Core را اجباری کنید، توجه داشته باشید که Grpc.Core منسوخ شده است و فقط برای نگهداری قدیمی درنظر گرفته شده است. برای کسب اطلاعات بیشتر، راهنمای استفاده پایه را ببینید.

نصب

بسته NuGet‏ Google.Ads.GoogleAds را بااستفاده از ابزار خط فرمان dotnet در پروژه‌تان نصب کنید:

dotnet add package Google.Ads.GoogleAds

برای بار کردن تنظیمات پیکربندی از appsettings.json، App.config، یا متغیرهای محیطی، بسته Google.Ads.GoogleAds.Extensions را نیز نصب کنید:

dotnet add package Google.Ads.GoogleAds.Extensions

اولین فراخوانی میانای برنامه‌سازی کاربردی را انجام دهید

برای استفاده از Google Ads API، باید چند مرحله را برای دسترسی به API و پیکربندی حساب‌های Google Ads خود انجام دهید. راهنمای راه‌اندازی سریع را دنبال کنید که شما را در تمام مراحل مهم، ازجمله راه‌اندازی حساب‌های Google Ads، راهنمایی می‌کند.

استفاده پایه

‫GoogleAdsConfig و GoogleAdsClient را با تنظیمات پیکربندی خود مقداردهی اولیه کنید، GoogleAdsServiceClient را بازیابی کنید، و ردیف‌های پویش را با SearchStream جاری‌سازی کنید:

using System;
using Google.Ads.Gax.Config;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Lib;
using Google.Ads.GoogleAds.V26.Errors;
using Google.Ads.GoogleAds.V26.Services;

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_CLIENT_ID.apps.googleusercontent.com",
    OAuth2ClientSecret = "INSERT_CLIENT_SECRET",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

GoogleAdsClient client = new GoogleAdsClient(config);
GoogleAdsServiceClient googleAdsService =
    client.GetService(Services.V26.GoogleAdsService);

string customerId = "INSERT_CUSTOMER_ID_HERE";
string query =
    "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id";

try
{
    googleAdsService.SearchStream(
        customerId,
        query,
        delegate (SearchGoogleAdsStreamResponse response)
        {
            foreach (GoogleAdsRow row in response.Results)
            {
                Console.WriteLine(
                    $"Campaign ID {row.Campaign.Id}: {row.Campaign.Name}");
            }
        });
}
catch (GoogleAdsException ex)
{
    Console.WriteLine($"Request ID {ex.RequestId} failed: {ex.Message}");
}

برای کسب اطلاعات بیشتر درباره نحوه استفاده از کتابخانه کارخواه NET.، به راهنمای استفاده پایه مراجعه کنید.

صدور مجوز و اصالت‌سنجی

کتابخانه کارخواه ‎ .NET از چندین رویکرد برای اصالت‌سنجی و صدور مجوز پشتیبانی می‌کند، ازجمله اعتبارنامه کاربر OAuth 2.0 (برای برنامه‌های وب و رایانه)، حساب‌های سرویس، «اعتبارنامه پیش‌فرض برنامه» (v24.1.0 و نسخه‌های جدیدتر)، و تزریق دستی اعتبارنامه (v27.0.0 و نسخه‌های جدیدتر). برای کسب اطلاعات بیشتر، به راهنمای مجوزدهی و اصالت‌سنجی مراجعه کنید.

پیکربندی و ثبت گزارش

کتابخانه کارخواه ‎ .NET از چندین گزینه پیکربندی و ثبت وقایع بااستفاده از اشیای زمان اجرا، appsettings.json یا فایل‌های JSON سفارشی، متغیرهای محیطی، یا فایل‌های App.config پشتیبانی می‌کند. درصورتی‌که لازم باشد رفتار ثبت گزارش کتابخانه کارخواه را اصلاح کنید، به راهنمای رهگیر gRPC سفارشی مراجعه کنید.

برنامه‌های کمکی

کتابخانه کارخواه ‎ .NET شامل کلاس‌های سودمندی برای بهبود قابلیت استفاده از API است، ازجمله کمک‌کننده‌های بارگذاری رسانه و ویدیو (UploadVideo در v27.2.0 و نسخه‌های جدیدتر). برای کسب اطلاعات بیشتر، به راهنماهای زیر مراجعه کنید:

تنظیم دقیق عملکرد برنامه

برای توصیه‌هایی درباره نحوه تنظیم دقیق عملکرد برنامه‌تان، به راهنمای تنظیم عملکرد مراجعه کنید.