ساختار تماس API

این راهنما ساختار مشترک همه فراخوانی‌های API را شرح می‌دهد.

اگر از یک کتابخانه کلاینت برای تعامل با API استفاده می‌کنید، نیازی به دانستن جزئیات درخواست‌های اساسی نخواهید داشت. با این حال، کمی دانش در مورد ساختار فراخوانی API می‌تواند هنگام آزمایش و اشکال‌زدایی مفید باشد.

API گوگل ادز یک API مبتنی بر gRPC با اتصالات REST است. این بدان معناست که دو روش برای فراخوانی API وجود دارد.

ترجیح داده شده :

  1. بدنه درخواست را به عنوان یک بافر پروتکل ایجاد کنید.

  2. آن را با استفاده از HTTP/2 به سرور ارسال کنید.

  3. پاسخ را به یک بافر پروتکل deserialize کنید.

  4. نتایج را تفسیر کنید.

بیشتر مستندات ما استفاده از gRPC را شرح می‌دهند.

اختیاری :

  1. بدنه درخواست را به عنوان یک شیء JSON ایجاد کنید.

  2. آن را با استفاده از HTTP 1.1 به سرور ارسال کنید.

  3. پاسخ را به صورت یک شیء JSON از حالت سریال خارج کنید.

  4. نتایج را تفسیر کنید.

برای اطلاعات بیشتر در مورد استفاده از REST به راهنمای رابط REST مراجعه کنید.

نام منابع

بیشتر اشیاء در API توسط رشته‌های نام منابع خود شناسایی می‌شوند. این رشته‌ها هنگام استفاده از رابط REST به عنوان URL نیز عمل می‌کنند. برای ساختار آنها به نام‌های منابع رابط REST مراجعه کنید.

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

اگر شناسه یک شیء به صورت سراسری منحصر به فرد نباشد، یک شناسه مرکب برای آن شیء با اضافه کردن شناسه والد آن و یک علامت ~ به ابتدای آن ساخته می‌شود.

برای مثال، از آنجایی که شناسه تبلیغ یک گروه تبلیغاتی به صورت سراسری منحصر به فرد نیست، شناسه شیء والد (گروه تبلیغاتی) را به آن اضافه می‌کنیم تا یک شناسه ترکیبی منحصر به فرد ایجاد کنیم:

  • AdGroupId 123 + ~ + AdGroupAdId 45678 = شناسه تبلیغ گروه تبلیغاتی ترکیبی 123~45678 .

درخواست سربرگ‌ها

اینها هدرهای HTTP (یا متادیتای grpc ) هستند که در بدنه درخواست همراه هستند:

مجوز

شما باید یک توکن دسترسی OAuth2 را به شکل Authorization: Bearer YOUR_ACCESS_TOKEN وارد کنید که یا یک حساب مدیر را که به نمایندگی از یک مشتری عمل می‌کند، یا یک تبلیغ‌کننده که مستقیماً حساب خود را مدیریت می‌کند، مشخص می‌کند. دستورالعمل‌های بازیابی توکن دسترسی را می‌توانید در راهنمای OAuth2 بیابید. یک توکن دسترسی به مدت یک ساعت پس از دریافت آن معتبر است. پس از انقضا، توکن دسترسی را برای بازیابی توکن جدید به‌روزرسانی کنید. توجه داشته باشید که کتابخانه‌های کلاینت ما به طور خودکار توکن‌های منقضی شده را به‌روزرسانی می‌کنند.

توکن توسعه‌دهنده

توکن توسعه‌دهنده یک رشته ۲۲ کاراکتری است که به طور منحصر به فرد یک توسعه‌دهنده API تبلیغات گوگل را شناسایی می‌کند. یک نمونه از رشته توکن توسعه‌دهنده ABcdeFGH93KL-NOPQ_STUv است. توکن توسعه‌دهنده باید به شکل developer-token : ABcdeFGH93KL-NOPQ_STUv درج شود.

ورود-شناسه-مشتری

این شناسه مشتریِ مجاز برای استفاده در درخواست، بدون خط تیره ( - ) است. اگر دسترسی شما به حساب مشتری از طریق حساب مدیر است، این سربرگ الزامی است و باید روی شناسه مشتری حساب مدیر تنظیم شود.

https://googleads.googleapis.com/v22/customers/1234567890/campaignBudgets:mutate

تنظیم login-customer-id معادل انتخاب یک حساب کاربری در رابط کاربری گوگل ادز پس از ورود به سیستم یا کلیک روی تصویر پروفایل شما در بالا سمت راست است. اگر این هدر را وارد نکنید، به طور پیش‌فرض روی operating customer قرار می‌گیرد.

شناسه مشتری مرتبط

این هدر فقط توسط [ارائه‌دهندگان تجزیه و تحلیل برنامه شخص ثالث هنگام آپلود تبدیل‌ها به یک حساب Google Ads مرتبط استفاده می‌شود.]

سناریویی را در نظر بگیرید که در آن کاربران حساب A از طریق ThirdPartyAppAnalyticsLink به حساب B دسترسی خواندن و ویرایش موجودیت‌های آن را می‌دهند. پس از اتصال، کاربر حساب B می‌تواند با توجه به مجوزهای ارائه شده توسط لینک، فراخوانی‌های API را علیه حساب A انجام دهد. در این حالت، مجوزهای فراخوانی API برای حساب A توسط لینک شخص ثالث به حساب B تعیین می‌شود، نه رابطه مدیر-حساب که در سایر فراخوانی‌های API استفاده می‌شود.

ارائه‌دهنده‌ی تحلیل برنامه‌ی شخص ثالث، یک فراخوانی API را به صورت زیر انجام می‌دهد:

  • linked-customer-id : حساب تحلیلی برنامه شخص ثالث که داده‌ها را آپلود می‌کند (حساب B ).
  • customer-id : حساب گوگل ادز که داده‌ها در آن آپلود می‌شوند (حساب A ).
  • سرآیند login-customer-id و Authorization : ترکیبی از مقادیر برای شناسایی کاربری که به حساب B دسترسی دارد.

هدرهای پاسخ

هدرهای زیر (یا grpc trailing-metadata ) به همراه بدنه پاسخ برگردانده می‌شوند. توصیه می‌کنیم این مقادیر را برای اهداف اشکال‌زدایی ثبت کنید.

شناسه درخواست

request-id رشته‌ای است که به طور منحصر به فرد این درخواست را مشخص می‌کند.

قبلی
فراداده منابع