نمونه ها

این راهنما شامل نمونه هایی از فراخوانی مستقیم نقاط انتهایی REST بدون استفاده از کتابخانه مشتری است.

پیش نیازها

تمام نمونه‌های زیر با استفاده از دستور curl باید در یک پوسته bash کپی و جایگذاری شوند.

همچنین به یک رمز توسعه دهنده نیاز دارید، دسترسی به حساب آزمایشی خوب است و یک حساب مدیر Google Ads حاوی حداقل یک حساب مشتری.

مهم: در این مثال‌ها، فرض می‌کنیم که شما به یک حساب مشتری ( CUSTOMER_ID ) توسط کاربری دسترسی دارید که دسترسی مدیریتی به یک حساب مدیر ( MANAGER_CUSTOMER_ID ) دارد که مستقیماً حساب مشتری را مدیریت می‌کند. اگر به‌جای آن مستقیماً به یک حساب مشتری منفرد دسترسی دارید، سرصفحه login-customer-id را حذف کنید یا آن را روی همان مقدار CUSTOMER_ID تنظیم کنید. توجه داشته باشید که برخی از نمونه‌ها، مانند ایجاد حساب‌ها ، به یک حساب مدیر نیاز دارند.

متغیرهای محیطی

اعتبارنامه ها و شناسه های حساب را در زیر وارد کنید و سپس در ترمینال خود کپی و جایگذاری کنید تا متغیرهای محیطی استفاده شده در مثال های بعدی را پیکربندی کنید. راهنمای مجوز دستورالعمل‌هایی را برای ایجاد نشانه دسترسی OAuth 2.0 ارائه می‌کند.

API_VERSION="17"
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 یک بودجه و کمپین جدید ایجاد می کنند.

جستجو کنید

راهنمای Query Cookbook شامل نمونه‌های گزارش بسیاری است که با برخی از صفحه‌های پیش‌فرض Google Ads مطابقت دارد و با متغیرهای محیطی مشابهی که در این راهنما استفاده شده است کار می‌کند. ابزار سازنده پرس و جو تعاملی ما همچنین یک منبع عالی برای ایجاد پرس و جوهای سفارشی به صورت تعاملی است.

صفحه بندی شده

روش search از صفحه بندی استفاده می کند، با اندازه صفحه ثابت 10000 مورد و یک 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 ، همه عملیات در درخواست موفق می شوند اگر و تنها در صورتی که همه آنها معتبر باشند.

مثال بعدی از یک کمپین موجود استفاده می کند. می توانید از خروجی 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 Ads را که با نشانه دسترسی 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 با padding کدگذاری می شوند. کدگذاری استاندارد یا ایمن URL base64 با یا بدون بالشتک پذیرفته می شود.

این مثال یک GIF 1 پیکسلی را رمزگذاری می کند تا نمونه را مختصر نگه دارد. در عمل، حجم data ها بسیار بزرگتر است.

از ابزار خط فرمان base64 (بخشی از ابزارهای هسته گنو ) برای رمزگذاری یک تصویر GIF 1 پیکسلی استفاده کنید.

base64 1pixel.gif

مقدار کدگذاری شده با base64 به عنوان ویژگی data در یک درخواست API مشخص می شود.

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'
      }
    }
  }
]
}"