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

الأمثلة

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

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

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

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

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

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

API_VERSION="21"
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

بخلاف ذلك، سيؤدي الخياران تعديل - إنشاء أمثلة إلى إنشاء ميزانية وحملة جديدتَين.

بحث

يحتوي دليل 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 "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'

Mutates

يمكن إرسال عمليات تعديل متعددة (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

Mutates

إنشاء

التحديثات

إزالة

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

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

إدارة الحساب

إنشاء حسابات

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

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

الأمثلة