يحتوي هذا الدليل على أمثلة لاستدعاء نقاط نهاية REST مباشرةً، بدون استخدام مكتبة عميل.
المتطلّبات الأساسية
يتم نسخ جميع النماذج الواردة أدناه ولصقها في bash Shell باستخدام الأمر curl.
يجب أيضًا الحصول على رمز مميّز للمطوِّر، مع إمكانية الوصول إلى حساب تجريبي، ويجب أن يكون لديك حساب إداري على "إعلانات Google" يتضمّن حساب عميل واحد على الأقل.
متغيرات البيئة
أدخِل بيانات اعتماد الحساب وأرقام تعريفه أدناه، ثم انسخه والصقها في الأداة الطرفية لضبط متغيّرات البيئة المستخدَمة في الأمثلة اللاحقة. يقدم دليل التفويض تعليمات لإنشاء رمز وصول OAuth 2.0.
API_VERSION="17"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"
أرقام تعريف عناصر اختيارية إضافية
تعمل بعض الأمثلة التالية على الميزانيات أو الحملات الموجودة مسبقًا. إذا كان لديك معرّفات لكائنات حالية لاستخدامها مع هذه الأمثلة، أدخلها أدناه.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
إذا لم تفعل ذلك، يؤدي التبديل - إنشاء أمثلة إلى إنشاء ميزانية وحملة جديدتين.
بحث
يحتوي دليل دليل طلبات البحث على العديد من نماذج التقارير التي تتوافق مع بعض شاشات "إعلانات Google" التلقائية وتعمل مع متغيرات البيئة نفسها المستخدَمة في هذا الدليل. تُعدّ أداة إنشاء طلبات البحث التفاعلية مصدرًا رائعًا أيضًا لإنشاء طلبات بحث مخصّصة بشكل تفاعلي.
مقسّم على صفحات
تستخدم الطريقة search
التقسيم على صفحات، مع تحديد حجم صفحة ثابت يبلغ 10,000 عنصر وتحديد page_token
بجانب query
.
cURL
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' ", "page_token":"${PAGE_TOKEN}" }'
واجهة برمجة التطبيقات Google Cloud Platform ( GAQL)
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
بالوضعَين الأفقي والعمودي
تعرض طريقة searchStream
جميع النتائج كاستجابة واحدة، وبالتالي لا يكون حقل pageSize
متاحًا.
cURL
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' " }'
واجهة برمجة التطبيقات Google Cloud Platform ( GAQL)
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
تبديل
يمكن إرسال عمليات تغيير متعدّدة (create
أو update
أو remove
) في نص طلب JSON واحد من خلال تعبئة المصفوفة operations
.
الإنشاء
ينشئ هذا المثال ميزانيتَين مشتركتَين للحملة في طلب واحد.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } }, { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } } ] }"
يستخدم المثال التالي BUDGET_ID
لميزانية حملة حالية، ويمكنك النسخ واللصق من ناتج الخطوة السابقة.
BUDGET_ID=BUDGET_ID
تستخدم الموارد التي تشير إلى موارد أخرى ذلك اسم المورد. وتشير الحملة التي تم إنشاؤها أدناه
إلى campaignBudget
من خلال اسم المورد المقيّم بالسلسلة.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}', 'targetSpend': {} } } ] }"
التحديثات
يمكنك تعديل سمات العناصر الحالية باستخدام عمليات update
. يستخدم المثال التالي حملة حالية، ويمكنك النسخ واللصق من ناتج الخطوة السابقة.
CAMPAIGN_ID=CAMPAIGN_ID
تتطلّب جميع التعديلات حقل updateMask
، وهو قائمة مفصولة بفواصل تضمّ سمات JSON المطلوب تضمينها في الطلب، ويجب تطبيقها كتحديث. يتم محو السمات المدرَجة في updateMask
ولكنّها غير متوفّرة في نص الطلب في أحد العناصر. ويتم تجاهل السمات غير المدرَجة في updateMask
، ولكنها متوفّرة في نص الطلب.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'name': 'A changed campaign name #${RANDOM}', }, 'updateMask': 'name' } ], }"
إزالة
وتتم إزالة العناصر من خلال تحديد اسم المورد الخاص بها كعملية remove
.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}' } ], }"
الأخطاء الجزئية
عند إجراء عدة عمليات في طلب واحد، يمكنك تحديد
partialFailure
اختياريًا. إذا كان true
، يتم تنفيذ عمليات ناجحة وتؤدّي
العمليات غير الصالحة إلى حدوث أخطاء. إذا كانت false
، ستنجح
جميع العمليات في الطلب إذا كانت جميعها صالحة فقط.
يستخدم المثال التالي حملة حالية، ويمكنك النسخ واللصق من الناتج مثال الإنشاءات.
CAMPAIGN_ID=CAMPAIGN_ID
يحتوي الطلب التالي على عمليتين. تحاول الطريقة الأولى تغيير استراتيجية عروض الأسعار للحملة المقدَّمة، وتحاول المحاولة التالية إزالة حملة ذات رقم تعريف غير صالح. بما أن العملية الثانية تؤدي إلى حدوث خطأ (رقم تعريف الحملة غير صالح) ولأن partialFailure
تم ضبط false
،
تتعذّر العملية الأولى أيضًا ولا يتم تعديل
استراتيجية عروض الأسعار للحملة الحالية.
curl --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'partialFailure': false, 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'manualCpc': { 'enhancedCpcEnabled': false } }, 'updateMask': 'manual_cpc.enhanced_cpc_enabled' }, { 'remove': 'customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID' } ] }"
العمليات المجمّعة
تدعم طريقة googleAds:mutate
إرسال مجموعات من العمليات التي تتضمن أنواعًا متعددة من الموارد. يمكنك إرسال العديد من العمليات من أنواع مختلفة
لربط سلسلة من العمليات معًا يجب تنفيذها كمجموعة.
وتنجح مجموعة العمليات إذا لم تخفق أي عملية أو إذا أخفقت أي عملية فردية.
يوضّح هذا المثال إنشاء ميزانية حملة وحملة ومجموعة إعلانية وإعلان معًا كمجموعة واحدة من الإجراءات. تعتمد كل عملية متتالية على العملية السابقة. وإذا فشلت إحداها، فستفشل مجموعة العمليات بأكملها.
تُستخدم الأعداد الصحيحة السالبة (-1
و-2
و-3
) كعناصر نائبة في أسماء الموارد، ويتم ملؤها ديناميكيًا في وقت التشغيل بنتائج تسلسل العمليات.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'mutateOperations': [ { 'campaignBudgetOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'name': 'My Campaign Budget #${RANDOM}', 'deliveryMethod': 'STANDARD', 'amountMicros': 500000, 'explicitlyShared': false } } }, { 'campaignOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/-2', 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'targetSpend': {} } } }, { 'adGroupOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/adGroups/-3', 'campaign': 'customers/${CUSTOMER_ID}/campaigns/-2', 'name': 'My ad group #${RANDOM}', 'status': 'PAUSED', 'type': 'SEARCH_STANDARD' } } }, { 'adGroupAdOperation': { 'create': { 'adGroup': 'customers/${CUSTOMER_ID}/adGroups/-3', 'status': 'PAUSED', 'ad': { 'responsiveSearchAd': { 'headlines': [ { 'pinned_field': 'HEADLINE_1', 'text': 'An example headline' }, { 'text': 'Another example headline' }, { 'text': 'Yet another headline' } ], 'descriptions': [ { 'text': 'An example description' }, { 'text': 'Another example description' } ], 'path1': 'all-inclusive', 'path2': 'deals' }, 'finalUrls': ['https://www.example.com'] } } } } ] }"
إدارة الحساب
إنشاء الحسابات
إنشاء حسابات جديدة باستخدام طريقة createCustomerClient
تجدر الإشارة إلى أنّ عنوان URL يتطلّب رقم تعريف حساب إداري بدلاً من رقم تعريف حساب عميل. يتم إنشاء حساب عميل جديد ضمن الحساب الإداري
curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'customerClient': { 'descriptiveName': 'My Client #${RANDOM}', 'currencyCode': 'USD', 'timeZone': 'America/New_York' } }"
بطاقة بيانات الحسابات التي يمكن الوصول إليها
يمكنك استخدام طلب GET
بسيط إلى الطريقة listAccessibleCustomers
للحصول على قائمة بحسابات "إعلانات Google" التي يمكن الوصول إليها باستخدام رمز الدخول OAuth 2.0 المحدَّد. يجب عدم استخدام أي أرقام تعريف
لحسابات العملاء في هذا الطلب.
curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
تحميل مواد العرض الثنائية
يتم استخدام الطريقة assets:mutate
لتحميل مواد العرض وإدارتها. يتم ترميز البيانات الثنائية، مثل الصور، كسلسلة باستخدام ترميز base64 العادي مع مساحة متروكة. يتم قبول ترميز base64 العادي أو الآمن لعنوان URL مع مساحة متروكة أو بدونها.
يتم في هذا المثال ترميز ملف GIF بحجم 1 بكسل لإبقاء النموذج موجزًا. من الناحية العملية،
تكون حمولات بيانات data
أكبر بكثير.
استخدِم أداة سطر الأوامر base64
(جزء من
أدوات GNU الأساسية) لترميز صورة GIF بحجم 1 بكسل.
base64 1pixel.gif
يتم تحديد القيمة base64 المرمّزة كسمة data
في طلب البيانات من واجهة برمجة التطبيقات.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My image asset #${RANDOM}', 'type': 'IMAGE', 'imageAsset': { 'data': 'R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIA' } } } ] }"