AdRuleService (v202502)

AI-generated Key Takeaways

• The AdRuleService is used to manage AdRule objects which generate video ad playlists.

• The service offers operations to create, retrieve by query, update, and perform actions on AdRule, AdSpot, and BreakTemplate objects.

• Numerous error types are defined for the AdRuleService, covering issues with dates, frequency caps, priorities, slots, targeting, and various general API problems.

• Specific errors are detailed for authentication, collection size, common issues, custom and geo targeting, internal server errors, and quota limitations.

• The document also outlines errors related to inventory targeting, null or missing required fields, parsing, permissions, podding, PQL queries, and various string format and length constraints.

Provides methods for creating, updating and retrieving AdRule objects.

Ad rules contain data that the ad server uses to generate a playlist of video ads.

---

Production WSDL

https://ads.google.com/apis/ads/publisher/v202502/AdRuleService?wsdl

Namespace

https://www.google.com/apis/ads/publisher/v202502

Operations

• createAdRules
• createAdSpots
• createBreakTemplates
• getAdRulesByStatement
• getAdSpotsByStatement
• getBreakTemplatesByStatement
• performAdRuleAction
• updateAdRules
• updateAdSpots
• updateBreakTemplates

Errors

• AdRuleDateError
• AdRuleError
• AdRuleFrequencyCapError
• AdRulePriorityError
• AdRuleSlotError
• AdRuleTargetingError
• ApiVersionError
• AuthenticationError
• CollectionSizeError
• CommonError
• CustomTargetingError
• FeatureError
• GeoTargetingError
• InternalApiError
• InventoryTargetingError
• NotNullError
• ParseError
• PermissionError
• PoddingError
• PublisherQueryLanguageContextError
• PublisherQueryLanguageSyntaxError
• QuotaError
• RequiredCollectionError
• RequiredError
• RequiredNumberError
• ServerError
• StatementError
• StringFormatError
• StringLengthError
• UniqueError

createAdRules

Creates new AdRule objects.

Parameters

Field	Type	Description
adRules	AdRule[]

Response

Field	Type	Description
rval	AdRule[]

createAdSpots

Creates new AdSpot objects.

Parameters

Field	Type	Description
adSpots	AdSpot[]

Response

Field	Type	Description
rval	AdSpot[]

createBreakTemplates

Creates new breakTemplate objects.

Parameters

Field	Type	Description
breakTemplate	BreakTemplate[]

Response

Field	Type	Description
rval	BreakTemplate[]

getAdRulesByStatement

Gets an AdRulePage of AdRule objects that satisfy the given Statement.query. The following fields are supported for filtering:

PQL Property	Object Property
id	AdRule.id (AdRule.adRuleId beginning in v201702)
name	AdRule.name
priority	AdRule.priority
status	AdRule.status

Parameters

Field	Type	Description
statement	Statement

Response

Field	Type	Description
rval	AdRulePage

getAdSpotsByStatement

Gets a AdSpotPage of AdSpot objects that satisfy the given Statement.query.

Parameters

Field	Type	Description
filterStatement	Statement

Response

Field	Type	Description
rval	AdSpotPage

getBreakTemplatesByStatement

Gets a BreakTemplatePage of BreakTemplate objects that satisfy the given Statement.query.

Parameters

Field	Type	Description
filterStatement	Statement

Response

Field	Type	Description
rval	BreakTemplatePage

performAdRuleAction

Performs actions on AdRule objects that match the given Statement.query.

Parameters

Field	Type	Description
adRuleAction	AdRuleAction ActivateAdRules DeactivateAdRules DeleteAdRules
filterStatement	Statement

Response

Field	Type	Description
rval	UpdateResult

updateAdRules

Updates the specified AdRule objects.

Parameters

Field	Type	Description
adRules	AdRule[]

Response

Field	Type	Description
rval	AdRule[]

updateAdSpots

Updates the specified AdSpot objects.

Parameters

Field	Type	Description
adSpots	AdSpot[]

Response

Field	Type	Description
rval	AdSpot[]

updateBreakTemplates

Updates the specified breakTemplate objects.

Parameters

Field	Type	Description
breakTemplate	BreakTemplate[]

Response

Field	Type	Description
rval	BreakTemplate[]

Errors

Error	Reasons
AdRuleDateError	Lists all errors associated with ad rule start and end dates. Enumerations START_DATE_TIME_IS_IN_PAST Cannot create a new ad rule with a start date in the past. END_DATE_TIME_IS_IN_PAST Cannot update an existing ad rule that has already completely passed with a new end date that is still in the past. END_DATE_TIME_NOT_AFTER_START_TIME End date must be after the start date. END_DATE_TIME_TOO_LATE DateTimes after 1 January 2037 are not supported. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
AdRuleError	Errors ad rule break template objects. Enumerations NAME_CONTAINS_INVALID_CHARACTERS The name contains unsupported or reserved characters. BREAK_TEMPLATE_MUST_HAVE_EXACTLY_ONE_FLEXIBLE_AD_SPOT The break template must have exactly one flexible ad spot. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
AdRuleFrequencyCapError	Errors related to ad rule frequency caps Enumerations NO_FREQUENCY_CAPS_SPECIFIED_WHEN_FREQUENCY_CAPS_TURNED_ON The ad rule specifies that frequency caps should be turned on, but then none of the frequency caps have actually been set. FREQUENCY_CAPS_SPECIFIED_WHEN_FREQUENCY_CAPS_TURNED_OFF The ad rule specifies that frequency caps should not be turned on, but then some frequency caps were actually set. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
AdRulePriorityError	Errors associated with ad rule priorities. Enumerations DUPLICATE_PRIORITY Ad rules must have unique priorities. PRIORITIES_NOT_SEQUENTIAL One or more priorities are missing. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
AdRuleSlotError	Errors related to ad rule slots. Enumerations DIFFERENT_STATUS_THAN_AD_RULE Has a different status than the ad rule to which it belongs. INVALID_VIDEO_AD_DURATION_RANGE Min video ad duration is greater than max video ad duration. INVALID_VIDEO_MIDROLL_FREQUENCY_TYPE Video mid-roll frequency type other than NONE for pre-roll or post-roll. MALFORMED_VIDEO_MIDROLL_FREQUENCY_CSV Invalid format for video mid-roll frequency when expecting a CSV list of numbers. Valid formats are the following: empty comma-separated list of numbers (time milliseconds or cue points) a single number (every n milliseconds or cue points, or one specific time / cue point) MALFORMED_VIDEO_MIDROLL_FREQUENCY_SINGLE_NUMBER Invalid format for video mid-roll frequency when expecting a single number only, e.g., every n seconds or every n cue points. INVALID_OVERLAY_AD_DURATION_RANGE Min overlay ad duration is greater than max overlay ad duration. INVALID_OVERLAY_MIDROLL_FREQUENCY_TYPE Overlay mid-roll frequency type other than NONE for pre-roll or post-roll. MALFORMED_OVERLAY_MIDROLL_FREQUENCY_CSV Invalid format for overlay mid-roll frequency for list of numbers. See valid formats above. MALFORMED_OVERLAY_MIDROLL_FREQUENCY_SINGLE_NUMBER Invalid format for overlay mid-roll frequency for a single number. INVALID_BUMPER_MAX_DURATION Non-positive bumper duration when expecting a positive number. TOO_MANY_MIDROLL_SLOTS_WITHOUT_ADS At most one mid-roll can be set to disallow ads. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
AdRuleTargetingError	Lists all errors associated with ad rule targeting. Enumerations VIDEO_POSITION_TARGETING_NOT_ALLOWED Cannot target video positions. EXACT_CUSTOM_VALUE_TARGETING_REQUIRED As part of COPPA requirements, custom targeting for session ad rules requires exact custom value matching. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
ApiVersionError	Errors related to the usage of API versions. Enumerations UPDATE_TO_NEWER_VERSION Indicates that the operation is not allowed in the version the request was made in. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
AuthenticationError	An error for an exception that occurred when authenticating. Enumerations AMBIGUOUS_SOAP_REQUEST_HEADER The SOAP message contains a request header with an ambiguous definition of the authentication header fields. This means either the authToken and oAuthToken fields were both null or both were specified. Exactly one value should be specified with each request. INVALID_EMAIL The login provided is invalid. AUTHENTICATION_FAILED Tried to authenticate with provided information, but failed. INVALID_OAUTH_SIGNATURE The OAuth provided is invalid. INVALID_SERVICE The specified service to use was not recognized. MISSING_SOAP_REQUEST_HEADER The SOAP message is missing a request header with an authToken and optional networkCode. MISSING_AUTHENTICATION_HTTP_HEADER The HTTP request is missing a request header with an authToken MISSING_AUTHENTICATION The request is missing an authToken NETWORK_API_ACCESS_DISABLED The network does not have API access enabled. NO_NETWORKS_TO_ACCESS The user is not associated with any network. NETWORK_NOT_FOUND No network for the given networkCode was found. NETWORK_CODE_REQUIRED The user has access to more than one network, but did not provide a networkCode. CONNECTION_ERROR An error happened on the server side during connection to authentication service. GOOGLE_ACCOUNT_ALREADY_ASSOCIATED_WITH_NETWORK The user tried to create a test network using an account that already is associated with a network. UNDER_INVESTIGATION The account is blocked and under investigation by the collections team. Please contact Google for more information. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
CollectionSizeError	Error for the size of the collection being too large Enumerations TOO_LARGE UNKNOWN The value returned if the actual value is not exposed by the requested API version.
CommonError	A place for common errors that can be used across services. Enumerations NOT_FOUND Indicates that an attempt was made to retrieve an entity that does not exist. ALREADY_EXISTS Indicates that an attempt was made to create an entity that already exists. NOT_APPLICABLE Indicates that a value is not applicable for given use case. DUPLICATE_OBJECT Indicates that two elements in the collection were identical. CANNOT_UPDATE Indicates that an attempt was made to change an immutable field. UNSUPPORTED_OPERATION Indicates that the requested operation is not supported. CONCURRENT_MODIFICATION Indicates that another request attempted to update the same data in the same network at about the same time. Please wait and try the request again. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
CustomTargetingError	Lists all errors related to CustomTargetingKey and CustomTargetingValue objects. Enumerations KEY_NOT_FOUND Requested CustomTargetingKey is not found. KEY_COUNT_TOO_LARGE Number of CustomTargetingKey objects created exceeds the limit allowed for the network. KEY_NAME_DUPLICATE CustomTargetingKey with the same CustomTargetingKey.name already exists. KEY_NAME_EMPTY CustomTargetingKey.name is empty. KEY_NAME_INVALID_LENGTH CustomTargetingKey.name is too long. KEY_NAME_INVALID_CHARS CustomTargetingKey.name contains unsupported or reserved characters. KEY_NAME_RESERVED CustomTargetingKey.name matches one of the reserved custom targeting key names. KEY_DISPLAY_NAME_INVALID_LENGTH CustomTargetingKey.displayName is too long. KEY_STATUS_NOT_ACTIVE Key is not active. VALUE_NOT_FOUND Requested CustomTargetingValue is not found. GET_VALUES_BY_STATEMENT_MUST_CONTAIN_KEY_ID The WHERE clause in the Statement.query must always contain CustomTargetingValue.customTargetingKeyId as one of its columns in a way that it is AND'ed with the rest of the query. VALUE_COUNT_FOR_KEY_TOO_LARGE The number of CustomTargetingValue objects associated with a CustomTargetingKey exceeds the network limit. This is only applicable for keys of type CustomTargetingKey.Type#PREDEFINED. VALUE_NAME_DUPLICATE CustomTargetingValue with the same CustomTargetingValue.name already exists. VALUE_NAME_EMPTY CustomTargetingValue.name is empty. VALUE_NAME_INVALID_LENGTH CustomTargetingValue.name is too long. VALUE_NAME_INVALID_CHARS CustomTargetingValue.name contains unsupported or reserved characters. VALUE_DISPLAY_NAME_INVALID_LENGTH CustomTargetingValue.displayName is too long. VALUE_MATCH_TYPE_NOT_ALLOWED Only Ad Manager 360 networks can have CustomTargetingValue.matchType other than CustomTargetingValue.MatchType.EXACT. VALUE_MATCH_TYPE_NOT_EXACT_FOR_PREDEFINED_KEY You can only create CustomTargetingValue objects with match type CustomTargetingValue.MatchType.EXACT when associating with CustomTargetingKey objects of type CustomTargetingKey.Type.PREDEFINED SUFFIX_MATCH_TYPE_NOT_ALLOWED CustomTargetingValue object cannot have match type of CustomTargetingValue.MatchType.SUFFIX when adding a CustomTargetingValue to a line item. CONTAINS_MATCH_TYPE_NOT_ALLOWED CustomTargetingValue object cannot have match type of CustomTargetingValue.MatchType.CONTAINS when adding a CustomTargetingValue to targeting expression of a line item. VALUE_STATUS_NOT_ACTIVE Value is not active. KEY_WITH_MISSING_VALUES The CustomTargetingKey does not have any CustomTargetingValue associated with it. INVALID_VALUE_FOR_KEY The CustomTargetingKey has a CustomTargetingValue specified for which the value is not a valid child. CANNOT_OR_DIFFERENT_KEYS CustomCriteriaSet.LogicalOperator.OR operation cannot be applied to values with different keys. INVALID_TARGETING_EXPRESSION Targeting expression is invalid. This can happen if the sequence of operators is wrong, or a node contains invalid number of children. DELETED_KEY_CANNOT_BE_USED_FOR_TARGETING The key has been deleted. CustomCriteria cannot have deleted keys. DELETED_VALUE_CANNOT_BE_USED_FOR_TARGETING The value has been deleted. CustomCriteria cannot have deleted values. VIDEO_BROWSE_BY_KEY_CANNOT_BE_USED_FOR_CUSTOM_TARGETING The key is set as the video browse-by key, which cannot be used for custom targeting. CANNOT_DELETE_CUSTOM_KEY_USED_IN_PARTNER_ASSIGNMENT_TARGETING Cannot delete a custom criteria key that is targeted by an active partner assignment. CANNOT_DELETE_CUSTOM_VALUE_USED_IN_PARTNER_ASSIGNMENT_TARGETING Cannot delete a custom criteria value that is targeted by an active partner assignment. CANNOT_TARGET_AUDIENCE_SEGMENT AudienceSegment object cannot be targeted. CANNOT_TARGET_THIRD_PARTY_AUDIENCE_SEGMENT Third party AudienceSegment cannot be targeted. CANNOT_TARGET_INACTIVE_AUDIENCE_SEGMENT Inactive AudienceSegment object cannot be targeted. INVALID_AUDIENCE_SEGMENTS Targeted AudienceSegment object is not valid. CANNOT_TARGET_MAPPED_METADATA Mapped metadata key-values are deprecated and cannot be targeted. ONLY_APPROVED_AUDIENCE_SEGMENTS_CAN_BE_TARGETED Targeted AudienceSegment objects have not been approved. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
FeatureError	Errors related to feature management. If you attempt using a feature that is not available to the current network you'll receive a FeatureError with the missing feature as the trigger. Enumerations MISSING_FEATURE A feature is being used that is not enabled on the current network. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
GeoTargetingError	Lists all errors associated with geographical targeting for a LineItem. Enumerations TARGETED_LOCATIONS_NOT_EXCLUDABLE A location that is targeted cannot also be excluded. EXCLUDED_LOCATIONS_CANNOT_HAVE_CHILDREN_TARGETED Excluded locations cannot have any of their children targeted. POSTAL_CODES_CANNOT_BE_EXCLUDED Postal codes cannot be excluded. UNTARGETABLE_LOCATION Indicates that location targeting is not allowed. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
InternalApiError	Indicates that a server-side error has occured. InternalApiErrors are generally not the result of an invalid request or message sent by the client. Enumerations UNEXPECTED_INTERNAL_API_ERROR API encountered an unexpected internal error. TRANSIENT_ERROR A temporary error occurred during the request. Please retry. UNKNOWN The cause of the error is not known or only defined in newer versions. DOWNTIME The API is currently unavailable for a planned downtime. ERROR_GENERATING_RESPONSE Mutate succeeded but server was unable to build response. Client should not retry mutate.
InventoryTargetingError	Lists all inventory errors caused by associating a line item with a targeting expression. Enumerations AT_LEAST_ONE_PLACEMENT_OR_INVENTORY_UNIT_REQUIRED At least one placement or inventory unit is required INVENTORY_CANNOT_BE_TARGETED_AND_EXCLUDED The same inventory unit or placement cannot be targeted and excluded at the same time INVENTORY_UNIT_CANNOT_BE_TARGETED_IF_ANCESTOR_IS_TARGETED A child inventory unit cannot be targeted if its ancestor inventory unit is also targeted. INVENTORY_UNIT_CANNOT_BE_TARGETED_IF_ANCESTOR_IS_EXCLUDED A child inventory unit cannot be targeted if its ancestor inventory unit is excluded. INVENTORY_UNIT_CANNOT_BE_EXCLUDED_IF_ANCESTOR_IS_EXCLUDED A child inventory unit cannot be excluded if its ancestor inventory unit is also excluded. EXPLICITLY_TARGETED_INVENTORY_UNIT_CANNOT_BE_TARGETED An explicitly targeted inventory unit cannot be targeted. EXPLICITLY_TARGETED_INVENTORY_UNIT_CANNOT_BE_EXCLUDED An explicitly targeted inventory unit cannot be excluded. SELF_ONLY_INVENTORY_UNIT_NOT_ALLOWED A landing page-only ad unit cannot be targeted. SELF_ONLY_INVENTORY_UNIT_WITHOUT_DESCENDANTS A landing page-only ad unit cannot be targeted if it doesn't have any children. YOUTUBE_AUDIENCE_SEGMENTS_CAN_ONLY_BE_TARGETED_WITH_YOUTUBE_SHARED_INVENTORY Audience segments shared from YouTube can only be targeted with inventory shared from YouTube for cross selling. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
NotNullError	Caused by supplying a null value for an attribute that cannot be null. Enumerations ARG1_NULL Assuming that a method will not have more than 3 arguments, if it does, return NULL ARG2_NULL ARG3_NULL NULL UNKNOWN The value returned if the actual value is not exposed by the requested API version.
ParseError	Lists errors related to parsing. Enumerations UNPARSABLE Indicates an error in parsing an attribute. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
PermissionError	Errors related to incorrect permission. Enumerations PERMISSION_DENIED User does not have the required permission for the request. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
PoddingError	Errors related to podding fields in ad rule slots. Enumerations INVALID_PODDING_TYPE_NONE Invalid podding type NONE, but has podding fields filled in. Podding types are defined in PoddingType. INVALID_PODDING_TYPE_STANDARD Invalid podding type STANDARD, but doesn't specify the max ads in pod and max ad duration podding fields. INVALID_OPTIMIZED_POD_WITHOUT_DURATION Invalid podding type OPTIMIZED, but doesn't specify pod duration. INVALID_OPTIMIZED_POD_WITHOUT_ADS Invalid optimized pod that does not specify a valid max ads in pod, which must either be a positive number or -1 to signify that there is no maximum. INVALID_POD_DURATION_RANGE Min pod ad duration is greater than max pod ad duration.
PublisherQueryLanguageContextError	An error that occurs while executing a PQL query contained in a Statement object. Enumerations UNEXECUTABLE Indicates that there was an error executing the PQL. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
PublisherQueryLanguageSyntaxError	An error that occurs while parsing a PQL query contained in a Statement object. Enumerations UNPARSABLE Indicates that there was a PQL syntax error. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
QuotaError	Describes a client-side error on which a user is attempting to perform an action to which they have no quota remaining. Enumerations EXCEEDED_QUOTA The number of requests made per second is too high and has exceeded the allowable limit. The recommended approach to handle this error is to wait about 5 seconds and then retry the request. Note that this does not guarantee the request will succeed. If it fails again, try increasing the wait time. Another way to mitigate this error is to limit requests to 8 per second for Ad Manager 360 accounts, or 2 per second for Ad Manager accounts. Once again this does not guarantee that every request will succeed, but may help reduce the number of times you receive this error. UNKNOWN The value returned if the actual value is not exposed by the requested API version. REPORT_JOB_LIMIT This user has exceeded the allowed number of new report requests per hour (this includes both reports run via the UI and reports run via ReportService.runReportJob). The recommended approach to handle this error is to wait about 10 minutes and then retry the request. Note that this does not guarantee the request will succeed. If it fails again, try increasing the wait time. Another way to mitigate this error is to limit the number of new report requests to 250 per hour per user. Once again, this does not guarantee that every request will succeed, but may help reduce the number of times you receive this error. SEGMENT_POPULATION_LIMIT This network has exceeded the allowed number of identifiers uploaded within a 24 hour period. The recommended approach to handle this error is to wait 30 minutes and then retry the request. Note that this does not guarantee the request will succeed. If it fails again, try increasing the wait time.
RequiredCollectionError	A list of all errors to be used for validating sizes of collections. Enumerations REQUIRED A required collection is missing. TOO_LARGE Collection size is too large. TOO_SMALL Collection size is too small. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
RequiredError	Errors due to missing required field. Enumerations REQUIRED Missing required field.
RequiredNumberError	A list of all errors to be used in conjunction with required number validators. Enumerations REQUIRED TOO_LARGE TOO_SMALL TOO_LARGE_WITH_DETAILS TOO_SMALL_WITH_DETAILS UNKNOWN The value returned if the actual value is not exposed by the requested API version.
ServerError	Errors related to the server. Enumerations SERVER_ERROR Indicates that an unexpected error occured. SERVER_BUSY Indicates that the server is currently experiencing a high load. Please wait and try your request again. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
StatementError	An error that occurs while parsing Statement objects. Enumerations VARIABLE_NOT_BOUND_TO_VALUE A bind variable has not been bound to a value. UNKNOWN The value returned if the actual value is not exposed by the requested API version.
StringFormatError	A list of error code for reporting invalid content of input strings. Enumerations UNKNOWN ILLEGAL_CHARS The input string value contains disallowed characters. INVALID_FORMAT The input string value is invalid for the associated field.
StringLengthError	Errors for Strings which do not meet given length constraints. Enumerations TOO_LONG TOO_SHORT UNKNOWN The value returned if the actual value is not exposed by the requested API version.
UniqueError	An error for a field which must satisfy a uniqueness constraint