تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الأمثلة

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

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

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

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

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

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

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

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

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

API_VERSION="22"
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}"
}'

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) في نص طلب 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 يتضمّن بكسل واحدًا للحفاظ على إيجاز العيّنة. في الواقع، تكون حمولات 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 "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'
      }
    }
  }
]
}"

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

تجربة

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

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

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

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

بحث

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

curl

GAQL

البث

curl

GAQL

التغييرات

إنشاء

التحديثات

إزالة

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

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

إدارة الحساب

إنشاء حسابات

إدراج الحسابات التي يمكن الوصول إليها

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

الأمثلة