تنبيه: يتم عرض مستندات واجهة REST API. تستخدم معظم مكتبات العملاء الرسمية خدمة gRPC. يمكنك الاطلاع على مقدمة عن REST للحصول على التفاصيل.

أمثلة

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

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

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

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

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

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

أدخل بيانات اعتماد الحساب وأرقام التعريف أدناه، ثم انسخ والصق المحطة الطرفية لتهيئة متغيرات البيئة المستخدمة في الأمثلة اللاحقة.

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

وإلا، فسينشئ نموذجا Mutates - Creates Example ميزانية وحملة جديدتين.

مقسّم إلى صفحات

تستخدم الطريقة search ترقيم الصفحات مع معلَمة pageSize قابلة للتعديل يتم تحديدها بجانب 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 '{
"pageSize": 10,
"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'

البث

تعمل الطريقة 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 إرسال مجموعات من العمليات تتضمن أنواعًا متعددة من الموارد. يمكنك إرسال العديد من العمليات من أنواع مختلفة لإنشاء سلسلة من العمليات التي يجب تنفيذها معًا كمجموعة. ستنجح مجموعة العمليات في حال تعذّر إتمام العملية أو إذا تعذّر إتمام عملية واحدة.

يوضح هذا المثال إنشاء ميزانية حملة وحملة ومجموعة إعلانية وإعلان معًا كمجموعة واحدة من الإجراءات. تعتمد كل عملية متعاقبة على العملية السابقة. وإذا فشلت إحدى العمليات، تتعذر مجموعة العمليات بالكامل.

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 قياسي مع مساحة متروكة. ويتم قبول إما تشفير قياسي أو عنوان URL عادي.

استخدِم الأداة المساعدة لسطر الأوامر base64 (وهي جزء من الأدوات المساعدة الأساسية GNU) لترميز صورة GIF بحجم 1 بكسل.

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'
      }
    }
  }
]
}"
السابق
طرق أخرى