ساختار فراخوانی 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 ) هستند که در بدنه درخواست همراه هستند:

مجوز

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