تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

الأمثلة

يحتوي هذا الدليل على أمثلة على طلب نقاط نهاية REST مباشرةً، بدون استخدام مكتبة برامج.

للاطّلاع على أمثلة أكثر تفصيلاً على الرموز البرمجية، يمكنك مراجعة مستودع GitHub لأمثلة على الرموز البرمجية لـ REST.

للاطّلاع على نصوص الطلبات والردود لكل طريقة من طرق واجهة برمجة التطبيقات، يُرجى الرجوع إلى المستندات المرجعية لنقاط نهاية الخدمة المحدّدة.

على سبيل المثال، تعرض صفحة المرجع لـ GoogleAdsService.Search نصَي الطلب والاستجابة للطريقة Search.

المتطلبات الأساسية

جميع النماذج المعروضة هنا مخصّصة للنسخ واللصق في bash shell باستخدام الأمر curl.

تحتاج أيضًا إلى مشروع على Google Cloud، وإذن وصول إلى حساب اختباري، وحساب إداري على "إعلانات Google" يحتوي على حساب عميل واحد على الأقل.

متغيّرات البيئة

أدخِل بيانات اعتماد الحساب وأرقام التعريف كما هو موضّح، ثم انسخها والصقها في جهازك لضبط متغيرات البيئة المستخدَمة في الأمثلة اللاحقة. يوفّر دليل التفويض تعليمات لإنشاء رمز مميّز للوصول عبر OAuth 2.0.

API_VERSION="26"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"

أرقام تعريف إضافية اختيارية للعناصر

تعمل بعض الأمثلة التالية على ميزانيات أو حملات حالية. إذا كانت لديك معرّفات لعناصر حالية لاستخدامها مع هذه الأمثلة، أدخِلها كما هو موضّح.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

بخلاف ذلك، ينشئ المثالان Mutates - Creates ميزانية وحملة جديدتَين.

بحث

يحتوي دليل Query Cookbook على العديد من نماذج إعداد التقارير التي تتوافق مع بعض شاشات "إعلانات 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 "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 "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) في نص طلب JSON واحد من خلال تعبئة مصفوفة operations.

إنشاء

ينشئ هذا المثال ميزانيتَين مشترَكتَين للحملة في طلب واحد.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \
--header "Content-Type: application/json" \
--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 "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 "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 "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 "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 "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 "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 "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \

تحميل مواد العرض الثنائية

يتم استخدام طريقة assets:mutate لتحميل مواد العرض وإدارتها. يتم ترميز البيانات الثنائية، مثل الصورة، كسلسلة باستخدام ترميز base64 العادي مع إضافة حشو. يتم قبول ترميز base64 العادي أو الآمن لعناوين URL مع أو بدون حشو.

يُرمِّز هذا المثال ملف GIF بحجم بكسل واحد لإبقاء النموذج موجزًا. وفي الواقع، تكون حمولات data أكبر بكثير.

استخدِم أداة سطر الأوامر base64 (جزء من أدوات GNU الأساسية) لترميز صورة 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 "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'
      }
    }
  }
]
}"

الأخطاء الشائعة

تجربة

الأمثلة تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

المتطلبات الأساسية

متغيّرات البيئة

أرقام تعريف إضافية اختيارية للعناصر

بحث

مُقسَّمة على صفحات

curl

GAQL

البث

curl

GAQL

تغييرات

إنشاء

التحديثات

إزالة

حالات الفشل الجزئية

العمليات المجمّعة

إدارة الحساب

إنشاء حسابات

عرض الحسابات التي يمكن الوصول إليها

تحميل مواد العرض الثنائية

الأمثلة