الأمثلة

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

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

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

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

ملاحظة مهمة: في هذه الأمثلة، نفترض أنّك تصل إلى حساب عميل (CUSTOMER_ID) من خلال مستخدم لديه إذن وصول إداري إلى حساب إداري (MANAGER_CUSTOMER_ID) يدير حساب العميل مباشرةً. إذا كنت بدلاً من ذلك تتعلّق بحساب عميل فردي مباشرةً، احذف عنوان login-customer-id أو اضبطه على القيمة نفسها التي تم ضبطها لعنوان CUSTOMER_ID. يُرجى العلم أنّ بعض الأمثلة، مثل إنشاء الحسابات، تتطلّب استخدام حساب مدير.

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

أدخِل بيانات اعتماد الحساب ومعرّفاته أدناه، ثم انسخها والصقها في الترميز البرمجي لضبط متغيّرات البيئة المستخدَمة في الأمثلة اللاحقة. يقدّم دليل تفويض الوصول تعليمات لإنشاء رمز مميز لوصول 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'
      }
    }
  }
]
}"