تفاصيل OAuth2 الداخلية لواجهة برمجة التطبيقات مع "إعلانات Google"
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتولّى مكتبات البرامج الخاصة بالعملاء تلقائيًا الاهتمام بالتفاصيل الموضّحة أدناه، لذا لا تواصِل القراءة إلا إذا كنت مهتمًا بمعرفة ما يحدث في الخلفية أو إذا كنت لا تستخدم إحدى مكتبات البرامج الخاصة بالعملاء.
يمكن أن يمنح رمز الدخول الواحد درجات متفاوتة من الوصول إلى واجهات برمجة تطبيقات متعددة. معلَمة متغيرة تُسمى scope تتحكّم في مجموعة الموارد والعمليات
التي يسمح بها رمز الدخول. أثناء طلب رمز الدخول، يرسل تطبيقك قيمة واحدة أو أكثر في المَعلمة scope.
نطاق Google Ads API هو:
https://www.googleapis.com/auth/adwords
الوصول إلى المحتوى بلا إنترنت
من الشائع أن يطلب تطبيق عميل Google Ads API إذن الوصول بلا إنترنت. على سبيل المثال، قد يرغب تطبيقك في تنفيذ مهام مجمّعة عندما لا يكون المستخدم متصلاً بالإنترنت ويتصفّح موقعك الإلكتروني.
لطلب إذن بالوصول إلى نوع تطبيق ويب بلا اتصال بالإنترنت، تأكَّد من ضبط المَعلمة access_type على offline. يمكنك العثور على معلومات إضافية في دليل OAuth2 من Google.
بالنسبة إلى نوع تطبيق الكمبيوتر المكتبي، يتم تفعيل إمكانية الوصول بلا إنترنت تلقائيًا، ولست بحاجة إلى طلبها صراحةً.
عناوين الطلبات
عناوين gRPC
عند استخدام gRPC API، يجب تضمين رمز الدخول في كل طلب. يمكنك ربط Credential بـ Channel لاستخدامه في جميع الطلبات على تلك القناة. يمكنك أيضًا إرسال بيانات اعتماد مخصّصة لكل مكالمة. يتضمّن دليل تفويض gRPC المزيد من التفاصيل حول التعامل مع التفويض.
عناوين REST
عند استخدام REST API، مرِّر رمز الدخول من خلال عنوان HTTP
Authorization. في ما يلي مثال على طلب HTTP:
في معظم الحالات، عليك تخزين رمز إعادة التحميل المميز بشكل آمن لاستخدامه في المستقبل.
لمزيد من المعلومات حول كيفية طلب رموز الدخول ورموز التحديث، يُرجى الاطّلاع على الدليل المناسب لنوع تطبيقك:
يحتوي رمز الدخول على وقت انتهاء صلاحية (استنادًا إلى قيمة
expires_in) يصبح بعده الرمز المميز غير صالح. يمكنك استخدام الرمز المميز لإعادة التحميل من أجل إعادة تحميل رمز دخول مميز انتهت صلاحيته. بشكلٍ تلقائي، تعمل مكتبات برامجنا على إعادة تحميل رموز الدخول المنتهية الصلاحية تلقائيًا.
تاريخ التعديل الأخير: 2025-09-05 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-09-05 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThis guide is for advanced users familiar with OAuth 2.0 and its use with Google APIs, offering behind-the-scenes details on authentication with the Google Ads API.\u003c/p\u003e\n"],["\u003cp\u003eAccess tokens control API access, determined by the 'scope' parameter, with the Google Ads API scope being \u003ccode\u003ehttps://www.googleapis.com/auth/adwords\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eOffline access is available for client apps; web apps require setting \u003ccode\u003eaccess_type\u003c/code\u003e to \u003ccode\u003eoffline\u003c/code\u003e, while desktop apps have it enabled by default.\u003c/p\u003e\n"],["\u003cp\u003eAccess tokens are passed via the \u003ccode\u003eAuthorization\u003c/code\u003e HTTP header for REST or bound to a \u003ccode\u003eChannel\u003c/code\u003e for gRPC, and can be refreshed using a securely stored refresh token.\u003c/p\u003e\n"],["\u003cp\u003eClient libraries automatically handle token refresh, but developers can consult guides for desktop and web app token management.\u003c/p\u003e\n"]]],[],null,["# OAuth2 Internals for Google Ads API\n\nOur client libraries automatically take care of the details covered below, so\ncontinue reading only if you're interested in what's happening behind the\nscenes, or if you're not using one of our client libraries.\n\nThis section is intended for advanced users who are already familiar\nwith the [OAuth 2.0 specification](//tools.ietf.org/html/rfc6749) and\nknow how to [use OAuth2 with Google APIs](/identity/protocols/oauth2).\n| **Note:** The Google Ads API does not currently support simultaneous signin with data access request (hybrid) or domain-wide delegation of authority (2LO).\n\n#### Want to learn more about authentication in the API?\n\n\nvideo_library\n[Video library: Authentication and Authorization](/google-ads/api/videos/catalog#authentication-authorization)\n\nScope\n-----\n\nA single access token can grant varying degrees of access to multiple APIs. A\nvariable parameter called `scope` controls the set of resources and operations\nthat an access token permits. During the access token request, your app\nsends one or more values in the `scope` parameter.\n\nThe scope for the Google Ads API is: \n\n https://www.googleapis.com/auth/adwords\n\nOffline access\n--------------\n\nIt's common for a Google Ads API client app to request offline access. For example,\nyour app may want to run batch jobs when your user is not physically online\nbrowsing your website.\n\nTo request offline access for a web app type, make sure you set the\n`access_type` parameter to `offline`. You can find additional information in\n[Google's OAuth2 guide](/identity/protocols/oauth2/web-server#offline).\n\nFor the desktop app type, offline access is enabled by default---you\ndon't have to explicitly request it.\n\nRequest headers\n---------------\n\n### gRPC headers\n\nWhen using the gRPC API, include the access token in each request. You can bind\na `Credential` to a `Channel` for use on all requests on that channel. You can\nalso send a customized credential for each call. The [gRPC\nAuthorization guide](//grpc.io/docs/guides/auth.html) contains more\ndetails on handling authorization.\n\n### REST headers\n\nWhen using the REST API, pass the access token through the HTTP header\n`Authorization`. An example HTTP request is shown below: \n\n```http\nGET /v21/customers/\u003cvar translate=\"no\"\u003e123456789\u003c/var\u003e HTTP/2\nHost: googleads.googleapis.com\nUser-Agent: INSERT_USER_AGENT\nAccept: */*\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eINSERT_ACCESS_TOKEN\u003c/var\u003e\ndeveloper-token: INSERT_DEVELOPER_TOKEN\n```\n\nAccess and refresh token\n------------------------\n\nIn most cases, you need to store the refresh token securely for future use.\nTo learn more about how to request access and refresh tokens, read the\ncorresponding guide for your application type:\n\n- [Desktop app](/identity/protocols/oauth2/native-app)\n- [Server-side web app](/identity/protocols/oauth2/web-server)\n\nRefresh token expiration\n------------------------\n\nFor more details about the refresh token expiration, refer to the [Google\nIdentity Platform OAuth documentation](/identity/protocols/oauth2#expiration).\n\nAccess token expiration\n-----------------------\n\nAn access token has an expiration time (based on the\n[`expires_in`](//tools.ietf.org/html/rfc6749#appendix-A.14) value) after\nwhich the token is no longer valid. You can use the refresh token to refresh\nan expired access token. By default, our client libraries automatically\nrefresh expired access tokens."]]
