Method: customers.recommendations.apply

套用附有對應套用參數的指定建議。

擲回錯誤清單：AuthenticationError AuthorizationError DatabaseError FieldError HeaderError InternalError MutateError QuotaError RecommendationError RequestError UrlFieldError

HTTP 要求

POST https://googleads.googleapis.com/v16/customers/{customerId}/recommendations:apply

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
customerId

string

必要欄位。建議項目的客戶 ID。

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "operations": [
    {
      object (ApplyRecommendationOperation)
    }
  ],
  "partialFailure": boolean
}
欄位
operations[]

object (ApplyRecommendationOperation)

必要欄位。要套用建議的作業清單。如果部分失敗=false 所有建議都應為相同類型，則每項要求最多只能執行 100 項作業。
partialFailure

boolean

若為 true，將會執行成功的作業，而且無效的作業也會傳回錯誤。如為 false，則只有在所有作業都有效時，才會以交易的形式執行。預設值為 false。

回應主體

「RecommendationService.ApplyRecommendation」的回應訊息。

如果成功，回應主體即會包含具有以下結構的資料：

JSON 表示法 
{
  "results": [
    {
      object (ApplyRecommendationResult)
    }
  ],
  "partialFailureError": {
    object (Status)
  }
}
欄位
results[]

object (ApplyRecommendationResult)

套用建議的作業結果。
partialFailureError

object (Status)

部分失敗模式下的作業失敗相關錯誤。只有在部分失敗 = true 且所有錯誤發生於作業內部時，才會傳回這個值。如果在作業之外發生任何錯誤 (例如驗證錯誤)，會傳回 RPC 層級錯誤。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/adwords

詳情請參閱 OAuth 2.0 總覽。

ApplyRecommendationOperation

關於套用建議的作業，以及用來自訂建議的作業相關資訊。

JSON 表示法 
{
  "resourceName": string,

  // Union field apply_parameters can be only one of the following:
  "campaignBudget": {
    object (CampaignBudgetParameters)
  },
  "textAd": {
    object (TextAdParameters)
  },
  "keyword": {
    object (KeywordParameters)
  },
  "targetCpaOptIn": {
    object (TargetCpaOptInParameters)
  },
  "targetRoasOptIn": {
    object (TargetRoasOptInParameters)
  },
  "calloutExtension": {
    object (CalloutExtensionParameters)
  },
  "callExtension": {
    object (CallExtensionParameters)
  },
  "sitelinkExtension": {
    object (SitelinkExtensionParameters)
  },
  "moveUnusedBudget": {
    object (MoveUnusedBudgetParameters)
  },
  "responsiveSearchAd": {
    object (ResponsiveSearchAdParameters)
  },
  "useBroadMatchKeyword": {
    object (UseBroadMatchKeywordParameters)
  },
  "responsiveSearchAdAsset": {
    object (ResponsiveSearchAdAssetParameters)
  },
  "responsiveSearchAdImproveAdStrength": {
    object (ResponsiveSearchAdImproveAdStrengthParameters)
  },
  "raiseTargetCpaBidTooLow": {
    object (RaiseTargetCpaBidTooLowParameters)
  },
  "forecastingSetTargetRoas": {
    object (ForecastingSetTargetRoasParameters)
  },
  "calloutAsset": {
    object (CalloutAssetParameters)
  },
  "callAsset": {
    object (CallAssetParameters)
  },
  "sitelinkAsset": {
    object (SitelinkAssetParameters)
  },
  "raiseTargetCpa": {
    object (RaiseTargetCpaParameters)
  },
  "lowerTargetRoas": {
    object (LowerTargetRoasParameters)
  },
  "forecastingSetTargetCpa": {
    object (ForecastingSetTargetCpaParameters)
  },
  "setTargetCpa": {
    object (ForecastingSetTargetCpaParameters)
  },
  "setTargetRoas": {
    object (ForecastingSetTargetRoasParameters)
  },
  "leadFormAsset": {
    object (LeadFormAssetParameters)
  }
  // End of list of possible types for union field apply_parameters.
}
欄位
resourceName

string

要套用的建議資源名稱。
聯集欄位 apply_parameters。套用建議時要使用的參數。apply_parameters 只能是下列其中一項：
campaignBudget

object (CampaignBudgetParameters)

套用廣告活動預算建議時要使用的選用參數。
textAd

object (TextAdParameters)

套用文字廣告建議時要使用的選用參數。
keyword

object (KeywordParameters)

套用關鍵字建議時要使用的選用參數。
targetCpaOptIn

object (TargetCpaOptInParameters)

套用目標單次轉換出價最佳化建議時要使用的選用參數。
targetRoasOptIn

object (TargetRoasOptInParameters)

套用目標廣告投資報酬率最佳化建議時要使用的選用參數。
calloutExtension

object (CalloutExtensionParameters)

套用摘要額外資訊建議時要使用的參數。
callExtension

object (CallExtensionParameters)

套用來電額外資訊建議時要使用的參數。
moveUnusedBudget

object (MoveUnusedBudgetParameters)

套用未使用的預算建議時要使用的參數。
responsiveSearchAd

object (ResponsiveSearchAdParameters)

套用回應式搜尋廣告建議時要使用的參數。
useBroadMatchKeyword

object (UseBroadMatchKeywordParameters)

套用使用廣泛比對關鍵字建議時要使用的參數。
responsiveSearchAdAsset

object (ResponsiveSearchAdAssetParameters)

套用回應式搜尋廣告素材資源最佳化建議時要使用的參數。
responsiveSearchAdImproveAdStrength

object (ResponsiveSearchAdImproveAdStrengthParameters)

套用回應式搜尋廣告時要使用的參數，可改善廣告優異度建議。
raiseTargetCpaBidTooLow

object (RaiseTargetCpaBidTooLowParameters)

套用提高目標單次轉換出價建議時要使用的參數太低。系統會非同步套用，視相關廣告活動中的廣告群組數量而定，這可能需要幾分鐘的時間。
forecastingSetTargetRoas

object (ForecastingSetTargetRoasParameters)

套用預測設定目標廣告投資報酬率建議時使用的參數。
calloutAsset

object (CalloutAssetParameters)

套用摘要素材資源最佳化建議時使用的參數。
callAsset

object (CallAssetParameters)

套用電話素材資源最佳化建議時使用的參數。
raiseTargetCpa

object (RaiseTargetCpaParameters)

套用「目標單次轉換出價」建議時要使用的參數。
lowerTargetRoas

object (LowerTargetRoasParameters)

套用目標廣告投資報酬率建議較低時要使用的參數。
forecastingSetTargetCpa

object (ForecastingSetTargetCpaParameters)

套用預測設定目標單次轉換出價建議時要使用的參數。
setTargetCpa

object (ForecastingSetTargetCpaParameters)

套用設定目標單次轉換出價建議時要使用的參數。
setTargetRoas

object (ForecastingSetTargetRoasParameters)

套用設定目標廣告投資報酬率建議時要使用的參數。
leadFormAsset

object (LeadFormAssetParameters)

套用待開發客戶表單素材資源最佳化建議時要使用的參數。

CampaignBudgetParameters

套用廣告活動預算建議時要使用的參數。

JSON 表示法 
{
  "newBudgetAmountMicros": string
}
欄位
newBudgetAmountMicros

string (int64 format)

要為目標預算資源設定的新預算金額。這是必填欄位。

TextAdParameters

套用文字廣告建議時要使用的參數。

JSON 表示法 
{
  "ad": {
    object (Ad)
  }
}
欄位
ad

object (Ad)

要加進建議廣告群組中的新廣告。您必須在這則訊息中設定所有必要欄位。這是必填欄位。

KeywordParameters

套用關鍵字建議時要使用的參數。

JSON 表示法 
{
  "matchType": enum (KeywordMatchType),
  "adGroup": string,
  "cpcBidMicros": string
}
欄位
matchType

enum (KeywordMatchType)

關鍵字的比對類型。這是必填欄位。
adGroup

string

要新增關鍵字的廣告群組資源。這是必填欄位。
cpcBidMicros

string (int64 format)

選填，為關鍵字設定的單次點擊出價。如未設定，關鍵字會使用目標廣告群組所使用的出價策略來設定出價。

TargetCpaOptInParameters

套用目標單次轉換出價建議時要使用的參數。

JSON 表示法 
{
  "targetCpaMicros": string,
  "newCampaignBudgetAmountMicros": string
}
欄位
targetCpaMicros

string (int64 format)

目標單次轉換出價策略使用的平均單次轉換出價。這是必填欄位。
newCampaignBudgetAmountMicros

string (int64 format)

選填，為廣告活動設定的預算金額。

TargetRoasOptInParameters

套用「目標廣告投資報酬率」最佳化建議時要使用的參數。

JSON 表示法 
{
  "targetRoas": number,
  "newCampaignBudgetAmountMicros": string
}
欄位
targetRoas

number

「目標廣告投資報酬率」出價策略使用的平均廣告投資報酬率 (每單位支出收益)。這個值必須介於 0.01 到 1000.0 (含) 之間。除非已設定 newCampaignBudgetAmountMicros，否則此為必填欄位。
newCampaignBudgetAmountMicros

string (int64 format)

選填，為廣告活動設定的預算金額。

CalloutExtensionParameters

套用摘要額外資訊建議時要使用的參數。

JSON 表示法 
{
  "calloutExtensions": [
    {
      object (CalloutFeedItem)
    }
  ]
}
欄位
calloutExtensions[]

object (CalloutFeedItem)

要新增的摘要額外資訊。這是必填欄位。

CallExtensionParameters

套用來電額外資訊建議時要使用的參數。

JSON 表示法 
{
  "callExtensions": [
    {
      object (CallFeedItem)
    }
  ]
}
欄位
callExtensions[]

object (CallFeedItem)

要新增的來電額外資訊。這是必填欄位。

SitelinkExtensionParameters

套用網站連結建議時要使用的參數。

JSON 表示法 
{
  "sitelinkExtensions": [
    {
      object (SitelinkFeedItem)
    }
  ]
}
欄位

MoveUnusedBudgetParameters

套用未使用的預算建議時要使用的參數。

JSON 表示法 
{
  "budgetMicrosToMove": string
}
欄位
budgetMicrosToMove

string (int64 format)

從超出預算挪用預算的金額。這是必填欄位。

ResponsiveSearchAdParameters

套用回應式搜尋廣告建議時要使用的參數。

JSON 表示法 
{
  "ad": {
    object (Ad)
  }
}
欄位
ad

object (Ad)

必要欄位。要加進建議廣告群組中的新廣告。

UseBroadMatchKeywordParameters

套用使用廣泛比對關鍵字建議時要使用的參數。

JSON 表示法 
{
  "newBudgetAmountMicros": string
}
欄位
newBudgetAmountMicros

string (int64 format)

要為目標預算資源設定的新預算金額。

ResponsiveSearchAdAssetParameters

套用回應式搜尋廣告素材資源最佳化建議時要使用的參數。

JSON 表示法 
{
  "updatedAd": {
    object (Ad)
  }
}
欄位
updatedAd

object (Ad)

已更新廣告。系統將替換目前廣告的內容。

ResponsiveSearchAdImproveAdStrengthParameters

套用回應式搜尋廣告時要使用的參數，可改善廣告優異度建議。

JSON 表示法 
{
  "updatedAd": {
    object (Ad)
  }
}
欄位
updatedAd

object (Ad)

已更新廣告。系統將替換目前廣告的內容。

RaiseTargetCpaBidTooLowParameters

套用提高目標單次轉換出價建議時要使用的參數太低。系統會非同步套用，視相關廣告活動中的廣告群組數量而定，這可能需要幾分鐘。

JSON 表示法 
{
  "targetMultiplier": number
}
欄位
targetMultiplier

number

必要欄位。大於 1.0 的數字，表示提高目標單次轉換出價的因素。這是必填欄位。

ForecastingSetTargetRoasParameters

套用預測設定目標廣告投資報酬率建議時要使用的參數。

JSON 表示法 
{
  "targetRoas": number,
  "campaignBudgetAmountMicros": string
}
欄位
targetRoas

number

必須為廣告活動資源設定新的目標廣告投資報酬率 (每單位支出收益)。這個值必須介於 0.01 到 1000.0 (含) 之間。
campaignBudgetAmountMicros

string (int64 format)

要為某個廣告活動資源設定新的廣告活動預算金額。

CalloutAssetParameters

套用摘要素材資源最佳化建議時使用的參數。

JSON 表示法 
{
  "adAssetApplyParameters": {
    object (AdAssetApplyParameters)
  }
}
欄位
adAssetApplyParameters

object (AdAssetApplyParameters)

必要欄位。要新增的摘要素材資源。這是必填欄位。

AdAssetApplyParameters

套用廣告素材資源最佳化建議時使用的常見參數。

JSON 表示法 
{
  "newAssets": [
    {
      object (Asset)
    }
  ],
  "existingAssets": [
    string
  ],
  "scope": enum (ApplyScope)
}
欄位
newAssets[]

object (Asset)

要建立並附加至特定範圍的資產。可與同一呼叫中的現有資產合併。
existingAssets[]

string

要附加至範圍的現有資產資源名稱。可於同一次呼叫中結合 newAssets。
scope

enum (ApplyScope)

必要欄位。資產的套用範圍。廣告活動層級層級的素材資源將套用至與這項建議相關聯的廣告活動。客戶範圍的素材資源將套用至整個帳戶。廣告活動範圍內的素材資源會覆寫客戶範圍附加的任何素材資源。

ApplyScope

要套用素材資源的範圍。

列舉
UNSPECIFIED 尚未指定套用範圍。
UNKNOWN 不明。
CUSTOMER 套用至客戶範圍。
CAMPAIGN 套用至廣告活動範圍。

CallAssetParameters

套用電話素材資源最佳化建議時使用的參數。

JSON 表示法 
{
  "adAssetApplyParameters": {
    object (AdAssetApplyParameters)
  }
}
欄位
adAssetApplyParameters

object (AdAssetApplyParameters)

必要欄位。要新增的電話素材資源。這是必填欄位。

SitelinkAssetParameters

套用網站連結素材資源最佳化建議時要使用的參數。

JSON 表示法 
{
  "adAssetApplyParameters": {
    object (AdAssetApplyParameters)
  }
}
欄位
adAssetApplyParameters

object (AdAssetApplyParameters)

必要欄位。要新增的網站連結素材資源。這是必填欄位。

RaiseTargetCpaParameters

套用「目標單次轉換出價」建議時要使用的參數。

JSON 表示法 
{
  "targetCpaMultiplier": number
}
欄位
targetCpaMultiplier

number

必要欄位。要設定單次轉換出價調節係數的目標。這是必填欄位。

LowerTargetRoasParameters

套用較低目標廣告投資報酬率建議時要使用的參數。

JSON 表示法 
{
  "targetRoasMultiplier": number
}
欄位
targetRoasMultiplier

number

必要欄位。要設定廣告投資報酬率調節係數的目標。這是必填欄位。

ForecastingSetTargetCpaParameters

套用固定目標單次轉換出價建議時使用的參數。

JSON 表示法 
{
  "targetCpaMicros": string,
  "campaignBudgetAmountMicros": string
}
欄位
targetCpaMicros

string (int64 format)

目標單次轉換出價策略使用的平均單次轉換出價。
campaignBudgetAmountMicros

string (int64 format)

要為某個廣告活動資源設定新的廣告活動預算金額。

LeadFormAssetParameters

套用待開發客戶表單素材資源最佳化建議時要使用的參數。

JSON 表示法 
{
  "adAssetApplyParameters": {
    object (AdAssetApplyParameters)
  },
  "setSubmitLeadFormAssetCampaignGoal": boolean
}
欄位
adAssetApplyParameters

object (AdAssetApplyParameters)

必要欄位。即將新增的待開發客戶表單素材資源。這是必填欄位。
setSubmitLeadFormAssetCampaignGoal

boolean

如果為 true，目標廣告活動就會設定「提交待開發客戶表單」目標。因此，廣告會以待開發客戶表單廣告素材廣告的形式顯示。如為 false，系統就不會在廣告活動中設定「提交待開發客戶表單」目標，而廣告會包含待開發客戶表單素材資源。

ApplyRecommendationResult

套用建議後的結果。

JSON 表示法 
{
  "resourceName": string
}
欄位
resourceName

string

如果符合條件，則會傳回此值。