يحتوي هذا الدليل على أمثلة على طلب نقاط نهاية REST مباشرةً، بدون استخدام مكتبة عملاء.
المتطلبات الأساسية
من المفترض نسخ جميع العيّنات أدناه ولصقها في bash shell باستخدام الأمر curl.
ستحتاج أيضًا إلى رمز مميّز للمطوّر، وإذن بالوصول إلى حساب اختباري، وحساب إداري على "إعلانات Google" يحتوي على حساب عميل واحد على الأقل.
متغيّرات البيئة
أدخِل بيانات اعتماد الحساب ومعرّفاته أدناه، ثم انسخها والصقها في الترميز البرمجي لضبط متغيّرات البيئة المستخدَمة في الأمثلة اللاحقة. يقدّم دليل تفويض الوصول تعليمات لإنشاء رمز مميز لوصول OAuth 2.0.
API_VERSION="19"
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" التلقائية وتعمل معvariabelsvariabels البيئة نفسها المستخدَمة في هذا الدليل. أداة إنشاء الطلبات المتفاعلة هي أيضًا مرجع رائع لإنشاء طلبات مخصّصة بشكل تفاعلي.
مُقسَّمة على صفحات
تستخدِم طريقة 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}" }'
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' " }'
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
) في ملف operations
واحد لطلب 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
. يتم تجاهل السمات غير المدرَجة في 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
، تنجح جميع العمليات في الطلب
إذا كانت جميعها صالحة فقط.
يستخدِم المثال التالي حملة حالية، ويمكنك النسخ واللصق من ناتج مثال Creates.
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 بحجم بكسل واحد لإبقاء العيّنة موجزة. من الناحية العملية، تكون حمولات
data
أكبر بكثير.
استخدِم أداة سطر الأوامر base64
(جزء من
GNU core utilities)
لترميز صورة GIF بدقة بكسل واحد.
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' } } } ] }"