تطبيقك الأول: المتطلّبات الأساسية
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
قبل أن تتمكّن من بدء ترميز تطبيق العميل الأول، هناك بعض الإجراءات التي
عليك اتّخاذها، إذا لم يسبق لك اتّخاذها.
إنشاء حساب على Google والحصول على أذونات "إعلانات شبكة البحث 360"
لاستخدام Search Ads 360 API، تحتاج إلى حساب Google وأذونات مناسبة
تم منحها لهذا الحساب من "إعلانات شبكة البحث 360":
إذا لم يكن لديك حساب على Google، يمكنك
إنشاء حساب.
اطلب من مدير وكالة في "إعلانات شبكة البحث 360"
إنشاء حساب مستخدم على "إعلانات شبكة البحث 360" لحسابك على Google.
لتنزيل التقارير، يجب أن يكون لديك إذن عرض للمعلِنين
الذين ستعمل معهم.
لإضافة إحالات ناجحة أو تعديلها، ستحتاج إلى إذن تعديل للمعلِنين
الذين ستتعامل معهم. في
إعدادات Floodlight المشتركة،
تحتاج إلى إذن تعديل لكل معلِن صغير تريد تحميل الإحالات الناجحة إليه.
لا تحتاج إلى الوصول إلى المعلِن الرئيسي أو الوصول إلى المعلِنين الفرعيين
الذين لا تُحمِّل إحالات ناجحة إليهم. إذا كنت تستخدم معرّفات النقرات لإسناد الإحالات الناجحة إلى الزيارات، تأكّد من أنّ لديك إذن تعديل حساب المعلن الذي أنشأ معرّف النقرة. إذا حدّدت معرّف نقرة من معلِن لا تملك الإذن بتعديله،
لن تتمّ معالجة الطلب.
يمكن لـ "مدير الوكالة" إعداد حسابك كمستخدِم معني لديه
إذن وصول إلى معلِنين محدّدين،
أو إعداد حسابك بمستوى وصول أعلى، مثل مستخدِم وكالة
لديه إذن وصول إلى جميع المعلِنين في الوكالة.
تفعيل خدمة الإحالات الناجحة في واجهة برمجة التطبيقات
إذا كنت تريد تحميل بيانات عن الإحالات الناجحة، على مستخدم على "إعلانات شبكة البحث 360" لديه امتيازات مدير الوكالة تسجيل الدخول إلى واجهة مستخدم "إعلانات شبكة البحث 360"
وتفعيل خدمة الإحالات الناجحة من خلال واجهة برمجة التطبيقات. اطّلِع على مركز مساعدة "إعلانات شبكة البحث 360" للحصول على التعليمات.
إنشاء مشروع على Google API Console وبيانات اعتماد OAuth لعميلك
- شغِّل
أداة إعداد وحدة تحكّم Google API.
ترشدك أداة الإعداد خلال عملية إنشاء مشروع (أو استخدام مشروع حالي)،
وتفعيل Search Ads 360 API، وإنشاء بيانات اعتماد OAuth 2.0.
- في صفحة تسجيل تطبيقك، اختَر مشروعًا حاليًا أو انقر على
إنشاء مشروع. وبعد ذلك، انقر على مواصلة.
- بعد أن تفعّل وحدة تحكّم واجهة برمجة التطبيقات في Google واجهة برمجة التطبيقات في "إعلانات شبكة البحث 360"، انقر على الزر
الانتقال إلى بيانات الاعتماد.
- في صفحة إنشاء بيانات الاعتماد، أدخِل المعلومات التالية:
-
ما هي واجهة برمجة التطبيقات التي تستخدمها؟: Search Ads 360 API
-
ما هي البيانات التي ستصل إليها؟: بيانات المستخدمين
- انقر على الزر Next (التالي).
تقدّم لك أداة الإعداد الآن المساعدة في إنشاء معرِّف عميل OAuth 2.0.
- اتّبِع بقية الخطوات الواردة في أداة الإعداد.
تثبيت sa360Api.py
توفّر "إعلانات شبكة البحث 360" نصًا برمجيًا لأداة تسهّل عملية إعداد
الإذن. يمكنك أيضًا استخدام هذا النص البرمجي لإرسال البيانات واستلامها بتنسيق JSON،
إذا كنت تريد تجربة إرسال البيانات واستلامها قبل تصميم تطبيق كامل
وكتابته. يمكنك نسخ العديد من أمثلة JSON في موقع المستندات هذا وإدخالها
مباشرةً في النص البرمجي.
لتثبيت النص البرمجي:
- ثبِّت الإصدار 2.7 من Python.
لا يعمل النص البرمجي مع Python 3.x.
- ثبِّت cURL.
- نزِّل sa360Api.zip.
- استخرِج
sa360Api.py من sa360Api.zip.
- اجعل
sa360Api.py قابلاً للتنفيذ.
التعرُّف على أساسيات REST
هناك طريقتان لاستدعاء واجهة برمجة التطبيقات:
إذا قررت عدم استخدام مكتبات البرامج، عليك فهم أساسيات REST.
REST هو نمط من بنية البرامج التي توفر نهجًا مناسبًا ومتسقًا لطلب البيانات وتعديلها.
إنّ المصطلح REST هو اختصار لـ "تحويل الولاية التمثيلية". في سياق Google APIs، يشير ذلك إلى استخدام أفعال HTTP لاسترداد وتعديل تمثيلات البيانات التي خزنتها Google.
في نظام RESTful، يتم تخزين الموارد في مستودع بيانات، ويرسل العميل طلبًا بأن ينفِّذ الخادم إجراءً معيّنًا (مثل إنشاء مورد أو استرجاعه أو تعديله أو حذفه)، وينفِّذ الخادم الإجراء ويرسل ردًا، غالبًا في شكل تمثيل للمورد المحدّد.
في واجهات برمجة التطبيقات RESTful من Google، يحدّد العميل إجراءً باستخدام فعل HTTP مثل POST أو GET أو PUT أو DELETE. وتحدّد هذه السمة موردًا باستخدام معرّف موارد منتظم فريد عالميًا بالشكل التالي:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
نظرًا لأن جميع موارد واجهة برمجة التطبيقات تتضمن معرفات موارد منتظمة (URI) فريدة يمكن الوصول إليها عبر HTTP، فإن REST تتيح التخزين المؤقت للبيانات ويتم تحسينها للعمل مع البنية الأساسية الموزعة على الويب.
قد تجد تعريفات الطريقة في مستندات معايير HTTP 1.1 مفيدة لأنّها تتضمّن مواصفات GET وPOST وPUT وDELETE.
واجهة برمجة التطبيقات REST في Search Ads 360 API
تتمّ ربط عمليات Search Ads 360 API مباشرةً بأفعال REST HTTP.
التنسيق المحدّد لعناوين URL لواجهة برمجة التطبيقات في "إعلانات شبكة البحث 360" هو:
https://www.googleapis.com/doubleclicksearch/v2/resourcePath?parameters
يتم تلخيص المجموعة الكاملة من معرفات الموارد المنتظمة (URI) المستخدمة لكل عملية متوافقة في واجهة برمجة التطبيقات في مرجع واجهة برمجة التطبيقات.
التعرّف على أساسيات JSON
في حال استخدام REST، عليك استخدام تنسيق JSON لنص الطلبات. يمكنك
تحديد أن تكون الردود بتنسيق JSON أو CSV.
JSON (JavaScript Object Notation) هو تنسيق بيانات شائع ولا يعتمد على اللغة ويقدم تمثيلاً نصيًا بسيطًا بُنى البيانات العشوائية. لمزيد من المعلومات، يُرجى الاطّلاع على json.org.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2024-11-07 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2024-11-07 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eBefore using the Search Ads 360 API, ensure you have a Google Account with the necessary Search Ads 360 permissions, which may include view or edit access to specific advertisers.\u003c/p\u003e\n"],["\u003cp\u003eTo upload conversion data, the API Conversion Service must be activated by a Search Ads 360 user with Agency Manager privileges.\u003c/p\u003e\n"],["\u003cp\u003eSet up a Google API Console project and obtain OAuth credentials for your client application to authenticate and authorize API access.\u003c/p\u003e\n"],["\u003cp\u003eInstall the provided \u003ccode\u003esa360Api.py\u003c/code\u003e utility script and familiarize yourself with REST and JSON basics if you plan to interact with the API directly without client libraries.\u003c/p\u003e\n"]]],["To start coding, create a Google Account and request Search Ads 360 permissions from an Agency Manager, who will grant view or edit access to advertisers. Activate the API conversion service via the Search Ads 360 UI. Next, create a Google API Console project and OAuth 2.0 credentials. Install Python 2.7, cURL, and the `sa360Api.py` utility script. Finally, understand REST basics and JSON formatting, crucial for interacting with the API using HTTP requests.\n"],null,["# Your First App: Prerequisites\n\nBefore you can start coding your first client application, there are a few things you\nneed to do, if you haven't done them already.\n\nCreate a Google Account and get Search Ads 360 permissions\n----------------------------------------------------------\n\nTo use the Search Ads 360 API, you need a Google Account and appropriate permissions\ngranted to that account from Search Ads 360:\n\n1. If you don't already have a Google Account, [create one](https://support.google.com/accounts/answer/27441).\n\n2. Ask a Search Ads 360 **Agency Manager** to [create a Search Ads 360 user](https://support.google.com/searchads/answer/6051717) for your Google Account.\n\n To download reports, you'll need **view permission** for the advertisers\n you'll be working with.\n\n To add or edit conversions, you'll need **edit permission** for the advertisers\n you'll be working with. In a\n [shared Floodlight configuration](https://support.google.com/searchads/answer/2458167),\n you need edit permission for each child advertiser you want to upload conversions into.\n You don't need access to the parent advertiser, nor do you need access to child advertisers\n that you're not uploading conversions into. If you use click IDs to\n [attribute\n conversions to visits](/search-ads/v2/how-tos/conversions/insert#attribute-a-conversion-to-a-specific-visit), make sure you have edit access to the advertiser that generated\n the click ID. If you specify a click ID from an advertiser you don't have edit access to,\n the request will not succeed.\n\n The Agency Manager can set up your account as an **Advertiser user** with\n access to specific advertisers,\n or set up your account with a higher level of access such as **Agency user**\n with access to all advertisers in the agency.\n\nActivate the API Conversion Service\n-----------------------------------\n\n\nIf you want to upload data about conversions, a Search Ads 360 user with **Agency\nManager** privileges needs to sign in to the Search Ads 360 UI and\n**activate the API conversion service** . See the\n[Search Ads 360\nhelp center](https://support.google.com/searchads/answer/2604604#activate) for instructions.\n\nCreate a Google API Console project and OAuth credentials for your client\n-------------------------------------------------------------------------\n\n1. Start the Google API Console [setup tool](https://console.cloud.google.com/start/api?id=doubleclicksearch&credential=client_key). \n The setup tool guides you through creating a project (or using an existing project), enabling the Search Ads 360 API, and creating OAuth 2.0 credentials.\n2. On the **Register your application** page, select an existing project or select **Create a project** . Then click **Continue**.\n3. After the Google API Console enables the Search Ads 360 API, click the **Go to credentials** button.\n4. On the **Create credentials** page, enter the following information:\n - **Which API are you using?**: Search Ads 360 API\n - **What data will you be accessing?**: User data\n5. Click the **Next** button.\n\n The setup tool now offers to help you create an **OAuth 2.0 client ID**.\n6. Follow the rest of the steps in the setup tool.\n\nInstall sa360Api.py\n-------------------\n\nSearch Ads 360 provides a utility script to facilitate the process of setting up\nauthorization. You can also use this script to send and receive data in the JSON format,\nif you want to try sending and receiving data before you design and write a full\napplication. You can copy many of the JSON examples in this documentation site and input\nthem directly to the script.\n\nTo install the script:\n\n1. [Install Python](http://www.python.org/getit/) 2.7. \n The script does not work with Python 3.x.\n2. [Install cURL](http://curl.haxx.se/download.html).\n3. [Download sa360Api.zip](https://www.google.com/help/hc/downloads/sa360/sa360Api.zip).\n4. Extract `sa360Api.py` from `sa360Api.zip`.\n5. Make `sa360Api.py` executable.\n\nLearn REST basics\n-----------------\n\nThere are two ways to invoke the API:\n\n- Using [client libraries](/search-ads/v2/libraries).\n- Sending HTTP requests and parsing the responses.\n\nIf you decide not to use client libraries, you'll need to understand the basics of\nREST.\n\nREST is a style of software architecture that provides a convenient and consistent approach to requesting and modifying data.\n\nThe term REST is short for \"[Representational State Transfer](https://en.wikipedia.org/wiki/Representational_state_transfer).\" In the context of Google APIs, it refers to using HTTP verbs to retrieve and modify representations of data stored by Google.\n\nIn a RESTful system, resources are stored in a data store; a client sends a request that the server perform a particular action (such as creating, retrieving, updating, or deleting a resource), and the server performs the action and sends a response, often in the form of a representation of the specified resource.\n\nIn Google's RESTful APIs, the client specifies an action using an HTTP verb such as `POST`, `GET`, `PUT`, or `DELETE`. It specifies a resource by a globally-unique URI of the following form: \n\n```\nhttps://www.googleapis.com/apiName/apiVersion/resourcePath?parameters\n```\n\nBecause all API resources have unique HTTP-accessible URIs, REST enables data caching and is optimized to work with the web's distributed infrastructure.\n\nYou may find the [method definitions](https://tools.ietf.org/html/rfc7231#section-4.3) in the HTTP 1.1 standards documentation useful; they include specifications for `GET`, `POST`, `PUT`, and `DELETE`.\n\n### REST in the Search Ads 360 API\n\nThe Search Ads 360 API operations map directly to REST HTTP verbs.\n\nThe specific format for Search Ads 360 API URIs is: \n\n```\nhttps://www.googleapis.com/doubleclicksearch/v2/resourcePath?parameters\n```\n\n\nThe full set of URIs used for each supported operation in the API is summarized in the [API Reference](/search-ads/v2/reference).\n\nLearn JSON basics\n-----------------\n\nIf you use REST, you'll need to use the JSON format for the request bodies. You can\nspecify that the responses be either in the JSON or CSV format.\n\n\n[JSON](http://en.wikipedia.org/wiki/JSON) (JavaScript Object Notation) is a common, language-independent data format that provides a simple text representation of arbitrary data structures. For more information, see [json.org](http://www.json.org/).\n\n\u003cbr /\u003e"]]
