Skip to main content
Google Ads API overview
Release notes
Authentication and authorization
Google Ads management
Create assets with generative AI (closed beta)
Create and manage campaigns
Report and monitor performance
Audience and creator insights
Develop applications
Test and troubleshoot your application
Productionize your application
Send feedback
Mutate Ads Stay organized with collections
Save and categorize content based on your preferences.
outlined_flag
Only certain ad types are mutable, and responsive search ads can be modified using the provided code examples in Java, C#, PHP, Python, Ruby, and Perl.
Pausing an ad is achieved by setting the status of the associated AdGroupAd to PAUSED
through the AdGroupAdService, as demonstrated with code in various programming languages.
You can mutate or pause an ad.
Mutate a responsive search ad
As mentioned previously
, only certain ad types are
mutable. The following code example illustrates how to modify an existing
responsive search ad.
Java
private
void
runExample
(
GoogleAdsClient
googleAdsClient
,
long
customerId
,
long
adId
)
{
// Creates an AdOperation to update an ad.
AdOperation
.
Builder
adOperation
=
AdOperation
.
newBuilder
();
// Creates an Ad in the update field of the operation.
Ad
.
Builder
adBuilder
=
adOperation
.
getUpdateBuilder
()
.
setResourceName
(
ResourceNames
.
ad
(
customerId
,
adId
))
.
addFinalUrls
(
"http://www.example.com/"
)
.
addFinalMobileUrls
(
"http://www.example.com/mobile"
);
// Sets the responsive search ad properties to update on the ad.
adBuilder
.
getResponsiveSearchAdBuilder
()
.
addAllHeadlines
(
ImmutableList
.
of
(
AdTextAsset
.
newBuilder
()
.
setText
(
"Cruise to Pluto #"
+
getShortPrintableDateTime
())
.
setPinnedField
(
ServedAssetFieldType
.
HEADLINE_1
)
.
build
(),
AdTextAsset
.
newBuilder
().
setText
(
"Tickets on sale now"
).
build
(),
AdTextAsset
.
newBuilder
().
setText
(
"Buy your ticket now"
).
build
()))
.
addAllDescriptions
(
ImmutableList
.
of
(
AdTextAsset
.
newBuilder
().
setText
(
"Best space cruise ever."
).
build
(),
AdTextAsset
.
newBuilder
()
.
setText
(
"The most wonderful space experience you will ever have."
)
.
build
()));
// Sets the update mask (the fields which will be modified) to be all the fields we set above.
adOperation
.
setUpdateMask
(
FieldMasks
.
allSetFieldsOf
(
adBuilder
.
build
()));
// Creates a service client to connect to the API.
try
(
AdServiceClient
adServiceClient
=
googleAdsClient
.
getLatestVersion
().
createAdServiceClient
())
{
// Issues the mutate request.
MutateAdsResponse
response
=
adServiceClient
.
mutateAds
(
String
.
valueOf
(
customerId
),
ImmutableList
.
of
(
adOperation
.
build
()));
// Displays the result.
for
(
MutateAdResult
result
:
response
.
getResultsList
())
{
System
.
out
.
printf
(
"Ad with resource name '%s' was updated.%n"
,
result
.
getResourceName
());
}
}
}
C#
public
void
Run
(
GoogleAdsClient
client
,
long
customerId
,
long
adId
)
{
// Get the AdService.
AdServiceClient
adService
=
client
.
GetService
(
Services
.
V22
.
AdService
);
Ad
ad
=
new
Ad
()
{
ResourceName
=
ResourceNames
.
Ad
(
customerId
,
adId
),
ResponsiveSearchAd
=
new
ResponsiveSearchAdInfo
()
{
// Update some properties of the responsive search ad.
Headlines
=
{
new
AdTextAsset
()
{
Text
=
"Cruise to Pluto #"
+
ExampleUtilities
.
GetShortRandomString
(),
PinnedField
=
ServedAssetFieldTypeEnum
.
Types
.
ServedAssetFieldType
.
Headline1
},
new
AdTextAsset
()
{
Text
=
"Tickets on sale now"
},
new
AdTextAsset
()
{
Text
=
"Buy your ticket now"
}
},
Descriptions
=
{
new
AdTextAsset
()
{
Text
=
"Best space cruise ever."
},
new
AdTextAsset
()
{
Text
=
"The most wonderful space experience you will ever have."
},
}
},
FinalUrls
=
{
"http://www.example.com/"
},
FinalMobileUrls
=
{
"http://www.example.com/mobile"
}
};
AdOperation
operation
=
new
AdOperation
()
{
Update
=
ad
,
UpdateMask
=
FieldMasks
.
AllSetFieldsOf
(
ad
)
};
try
{
// Issue the update request.
MutateAdsResponse
response
=
adService
.
MutateAds
(
customerId
.
ToString
(),
new
[]
{
operation
});
// Display the results.
foreach
(
MutateAdResult
updatedAd
in
response
.
Results
)
{
Console
.
WriteLine
(
$"Ad with resource ID = '{updatedAd.ResourceName}' was "
+
$"updated."
);
}
}
catch
(
GoogleAdsException
e
)
{
Console
.
WriteLine
(
"Failure:"
);
Console
.
WriteLine
(
$"Message: {e.Message}"
);
Console
.
WriteLine
(
$"Failure: {e.Failure}"
);
Console
.
WriteLine
(
$"Request ID: {e.RequestId}"
);
throw
;
}
}
PHP
public static function runExample(
GoogleAdsClient $googleAdsClient,
int $customerId,
int $adId
) {
// Creates an ad with the specified resource name and other changes.
$ad = new Ad([
'resource_name' => ResourceNames::forAd($customerId, $adId),
'responsive_search_ad' => new ResponsiveSearchAdInfo([
// Update some properties of the responsive search ad.
'headlines' => [
new AdTextAsset([
'text' => 'Cruise to Pluto #' . Helper::getShortPrintableDatetime(),
'pinned_field' => ServedAssetFieldType::HEADLINE_1
]),
new AdTextAsset(['text' => 'Tickets on sale now']),
new AdTextAsset(['text' => 'Buy your ticket now'])
],
'descriptions' => [
new AdTextAsset(['text' => 'Best space cruise ever.']),
new AdTextAsset([
'text' => 'The most wonderful space experience you will ever have.'])
]
]),
'final_urls' => ['http://www.example.com'],
'final_mobile_urls' => ['http://www.example.com/mobile']
]);
// Constructs an operation that will update the ad, using the FieldMasks to derive the
// update mask. This mask tells the Google Ads API which attributes of the ad you want to
// change.
$adOperation = new AdOperation();
$adOperation->setUpdate($ad);
$adOperation->setUpdateMask(FieldMasks::allSetFieldsOf($ad));
// Issues a mutate request to update the ad.
$adServiceClient = $googleAdsClient->getAdServiceClient();
$response =
$adServiceClient->mutateAds(MutateAdsRequest::build($customerId, [$adOperation]));
// Prints the resource name of the updated ad.
/** @var Ad $updatedAd */
$updatedAd = $response->getResults()[0];
printf(
"Updated ad with resource name: '%s'.%s",
$updatedAd->getResourceName(),
PHP_EOL
);
}
Python
def
main
(
client
:
GoogleAdsClient
,
customer_id
:
str
,
ad_id
:
str
)
-
> None
:
ad_service
:
AdServiceClient
=
client
.
get_service
(
"AdService"
)
ad_operation
:
AdOperation
=
client
.
get_type
(
"AdOperation"
)
# Update ad operation.
ad
:
Ad
=
ad_operation
.
update
ad
.
resource_name
=
ad_service
.
ad_path
(
customer_id
,
ad_id
)
# Update some properties of the responsive search ad.
headline_1
:
AdTextAsset
=
client
.
get_type
(
"AdTextAsset"
)
headline_1
.
text
=
f
"Cruise to Pluto #
{
uuid4
()
.
hex
[:
8
]
}
"
headline_1
.
pinned_field
=
client
.
enums
.
ServedAssetFieldTypeEnum
.
HEADLINE_1
headline_2
:
AdTextAsset
=
client
.
get_type
(
"AdTextAsset"
)
headline_2
.
text
=
"Tickets on sale now"
headline_3
:
AdTextAsset
=
client
.
get_type
(
"AdTextAsset"
)
headline_3
.
text
=
"Buy your tickets now"
ad
.
responsive_search_ad
.
headlines
.
extend
(
[
headline_1
,
headline_2
,
headline_3
]
)
description_1
:
AdTextAsset
=
client
.
get_type
(
"AdTextAsset"
)
description_1
.
text
=
"Best space cruise ever."
description_2
:
AdTextAsset
=
client
.
get_type
(
"AdTextAsset"
)
description_2
.
text
=
(
"The most wonderful space experience you will ever have."
)
ad
.
responsive_search_ad
.
descriptions
.
extend
([
description_1
,
description_2
])
ad
.
final_urls
.
append
(
"https://www.example.com"
)
ad
.
final_mobile_urls
.
append
(
"https://www.example.com/mobile"
)
client
.
copy_from
(
ad_operation
.
update_mask
,
protobuf_helpers
.
field_mask
(
None
,
ad
.
_pb
)
)
# Updates the ad.
operations
:
List
[
AdOperation
]
=
[
ad_operation
]
ad_response
:
MutateAdsResponse
=
ad_service
.
mutate_ads
(
customer_id
=
customer_id
,
operations
=
operations
)
print
(
f
'Ad with resource name "
{
ad_response
.
results
[
0
]
.
resource_name
}
" '
"was updated."
)
Ruby
def
update_responsive_search_ad
(
customer_id
,
ad_id
)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client
=
Google
::
Ads
::
GoogleAds
::
GoogleAdsClient
.
new
ad_resource_name
=
client
.
path
.
ad
(
customer_id
,
ad_id
)
# Create the operation for updating the ad.
ad_operation
=
client
.
operation
.
update_resource
.
ad
(
ad_resource_name
)
do
|
ad
|
ad
.
final_urls
<<
'http://www.example.com'
ad
.
final_mobile_urls
<<
'http://www.example.com/mobile'
ad
.
responsive_search_ad
=
client
.
resource
.
responsive_search_ad_info
do
|
rsa
|
rsa
.
headlines
+=
[
client
.
resource
.
ad_text_asset
do
|
ata
|
ata
.
text
=
"Cruise to Pluto
#{
(
Time
.
new
.
to_f
*
100
)
.
to_i
}
"
ata
.
pinned_field
=
:HEADLINE_1
end
,
client
.
resource
.
ad_text_asset
do
|
ata
|
ata
.
text
=
"Tickets on sale now"
end
,
client
.
resource
.
ad_text_asset
do
|
ata
|
ata
.
text
=
"Buy your ticket now"
end
,
]
rsa
.
descriptions
+=
[
client
.
resource
.
ad_text_asset
do
|
ata
|
ata
.
text
=
"Best space cruise ever"
end
,
client
.
resource
.
ad_text_asset
do
|
ata
|
ata
.
text
=
"The most wonderful space experience you will ever have"
end
,
]
end
end
# Update the ad.
response
=
client
.
service
.
ad
.
mutate_ads
(
customer_id
:
customer_id
,
operations
:
[
ad_operation
]
,
)
puts
"Updated responsive search ad
#{
response
.
results
.
first
.
resource_name
}
."
end
.
rb
Perl
sub
update_responsive_search_ad
{
my
(
$api_client
,
$customer_id
,
$ad_id
)
=
@_
;
# Create an ad with the proper resource name and any other changes.
my
$ad
=
Google::Ads::GoogleAds::V22::Resources::
Ad
-
> new
({
resourceName
=
> Google::Ads::GoogleAds::V22::Utils::ResourceNames::
ad
(
$customer_id
,
$ad_id
),
responsiveSearchAd
=
> Google::Ads::GoogleAds::V22::Common::
ResponsiveSearchAdInfo
-
> new
({
# Update some properties of the responsive search ad.
headlines
=
> [
Google::Ads::GoogleAds::V22::Common::
AdTextAsset
-
> new
({
text
=
> "Cruise to Pluto #"
.
uniqid
(),
pinnedField
=
> HEADLINE_1
}
),
Google::Ads::GoogleAds::V22::Common::
AdTextAsset
-
> new
({
text
=
> "Tickets on sale now"
}
),
Google::Ads::GoogleAds::V22::Common::
AdTextAsset
-
> new
({
text
=
> "Buy your ticket now"
}
),
],
descriptions
=
> [
Google::Ads::GoogleAds::V22::Common::
AdTextAsset
-
> new
({
text
=
> "Best space cruise ever."
}
),
Google::Ads::GoogleAds::V22::Common::
AdTextAsset
-
> new
({
text
=
> "The most wonderful space experience you will ever have."
}
),
]}
),
finalUrls
=
> [
"http://www.example.com/"
],
finalMobileUrls
=
> [
"http://www.example.com/mobile"
]});
# Create an ad operation for update, using the FieldMasks utility to derive
# the update mask.
my
$ad_operation
=
Google::Ads::GoogleAds::V22::Services::AdService::
AdOperation
-
> new
({
update
=
> $ad
,
updateMask
=
> all_set_fields_of
(
$ad
)});
# Issue a mutate request to update the ad.
my
$ads_response
=
$api_client
-
> AdService
()
-
> mutate
({
customerId
=
> $customer_id
,
operations
=
> [
$ad_operation
]});
printf
"Updated ad with resource name: '%s'.\n"
,
$ads_response
-
> {
results
}[
0
]{
resourceName
};
return
1
;
}
Pause an ad
To pause an ad, set the status of the AdGroupAd
to which it belongs to PAUSED
:
Java
// Copyright 2018 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package
com.google.ads.googleads.examples.basicoperations
;
import
com.beust.jcommander.Parameter
;
import
com.google.ads.googleads.examples.utils.ArgumentNames
;
import
com.google.ads.googleads.examples.utils.CodeSampleParams
;
import
com.google.ads.googleads.lib.GoogleAdsClient
;
import
com.google.ads.googleads.lib.utils.FieldMasks
;
import
com.google.ads.googleads.v22.enums.AdGroupAdStatusEnum.AdGroupAdStatus
;
import
com.google.ads.googleads.v22.errors.GoogleAdsError
;
import
com.google.ads.googleads.v22.errors.GoogleAdsException
;
import
com.google.ads.googleads.v22.resources.AdGroupAd
;
import
com.google.ads.googleads.v22.services.AdGroupAdOperation
;
import
com.google.ads.googleads.v22.services.AdGroupAdServiceClient
;
import
com.google.ads.googleads.v22.services.MutateAdGroupAdResult
;
import
com.google.ads.googleads.v22.services.MutateAdGroupAdsResponse
;
import
com.google.ads.googleads.v22.utils.ResourceNames
;
import
com.google.common.collect.ImmutableList
;
import
java.io.FileNotFoundException
;
import
java.io.IOException
;
/** Changes the status of a given ad to {@code PAUSED}. */
public
class
PauseAd
{
private
static
class
PauseAdParams
extends
CodeSampleParams
{
@Parameter
(
names
=
ArgumentNames
.
CUSTOMER_ID
,
required
=
true
)
private
Long
customerId
;
@Parameter
(
names
=
ArgumentNames
.
AD_GROUP_ID
,
required
=
true
)
private
Long
adGroupId
;
@Parameter
(
names
=
ArgumentNames
.
AD_ID
,
required
=
true
)
private
Long
adId
;
}
public
static
void
main
(
String
[]
args
)
{
PauseAdParams
params
=
new
PauseAdParams
();
if
(
!
params
.
parseArguments
(
args
))
{
// Either pass the required parameters for this example on the command line, or insert them
// into the code here. See the parameter class definition above for descriptions.
params
.
customerId
=
Long
.
parseLong
(
"INSERT_CUSTOMER_ID_HERE"
);
params
.
adGroupId
=
Long
.
parseLong
(
"INSERT_AD_GROUP_ID_HERE"
);
params
.
adId
=
Long
.
parseLong
(
"INSERT_AD_ID_HERE"
);
}
GoogleAdsClient
googleAdsClient
=
null
;
try
{
googleAdsClient
=
GoogleAdsClient
.
newBuilder
().
fromPropertiesFile
().
build
();
}
catch
(
FileNotFoundException
fnfe
)
{
System
.
err
.
printf
(
"Failed to load GoogleAdsClient configuration from file. Exception: %s%n"
,
fnfe
);
System
.
exit
(
1
);
}
catch
(
IOException
ioe
)
{
System
.
err
.
printf
(
"Failed to create GoogleAdsClient. Exception: %s%n"
,
ioe
);
System
.
exit
(
1
);
}
try
{
new
PauseAd
().
runExample
(
googleAdsClient
,
params
.
customerId
,
params
.
adGroupId
,
params
.
adId
);
}
catch
(
GoogleAdsException
gae
)
{
// GoogleAdsException is the base class for most exceptions thrown by an API request.
// Instances of this exception have a message and a GoogleAdsFailure that contains a
// collection of GoogleAdsErrors that indicate the underlying causes of the
// GoogleAdsException.
System
.
err
.
printf
(
"Request ID %s failed due to GoogleAdsException. Underlying errors:%n"
,
gae
.
getRequestId
());
int
i
=
0
;
for
(
GoogleAdsError
googleAdsError
:
gae
.
getGoogleAdsFailure
().
getErrorsList
())
{
System
.
err
.
printf
(
" Error %d: %s%n"
,
i
++
,
googleAdsError
);
}
System
.
exit
(
1
);
}
}
/**
* Runs the example.
*
* @param googleAdsClient the Google Ads API client.
* @param customerId the client customer ID.
* @param adGroupId the ad group ID.
* @param adId the ID of the ad to pause.
* @throws GoogleAdsException if an API request failed with one or more service errors.
*/
private
void
runExample
(
GoogleAdsClient
googleAdsClient
,
long
customerId
,
long
adGroupId
,
long
adId
)
{
String
adGroupAdResourceName
=
ResourceNames
.
adGroupAd
(
customerId
,
adGroupId
,
adId
);
// Creates an ad representation with its status set to PAUSED.
AdGroupAd
adGroupAd
=
AdGroupAd
.
newBuilder
()
.
setResourceName
(
adGroupAdResourceName
)
.
setStatus
(
AdGroupAdStatus
.
PAUSED
)
.
build
();
AdGroupAdOperation
op
=
AdGroupAdOperation
.
newBuilder
()
.
setUpdate
(
adGroupAd
)
.
setUpdateMask
(
FieldMasks
.
allSetFieldsOf
(
adGroupAd
))
.
build
();
try
(
AdGroupAdServiceClient
adGroupAdServiceClient
=
googleAdsClient
.
getLatestVersion
().
createAdGroupAdServiceClient
())
{
MutateAdGroupAdsResponse
response
=
adGroupAdServiceClient
.
mutateAdGroupAds
(
Long
.
toString
(
customerId
),
ImmutableList
.
of
(
op
));
for
(
MutateAdGroupAdResult
result
:
response
.
getResultsList
())
{
System
.
out
.
printf
(
"Ad with resource name '%s' is paused.%n"
,
result
.
getResourceName
());
}
}
}
}
C#
// Copyright 2019 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
using
CommandLine
;
using
Google.Ads.Gax.Examples
;
using
Google.Ads.Gax.Util
;
using
Google.Ads.GoogleAds.Lib
;
using
Google.Ads.GoogleAds.V22.Errors
;
using
Google.Ads.GoogleAds.V22.Resources
;
using
Google.Ads.GoogleAds.V22.Services
;
using
System
;
using
System.Collections.Generic
;
using
static
Google
.
Ads
.
GoogleAds
.
V22
.
Enums
.
AdGroupAdStatusEnum
.
Types
;
namespace
Google.Ads.GoogleAds.Examples.V22
{
/// <summary>
/// This code example pauses a given ad. To list all ads, run GetExpandedTextAds.cs.
/// </summary>
public
class
PauseAd
:
ExampleBase
{
/// <summary>
/// Command line options for running the <see cref="PauseAd"/> example.
/// </summary>
public
class
Options
:
OptionsBase
{
/// <summary>
/// The customer ID for which the call is made.
/// </summary>
[Option("customerId", Required = true, HelpText =
"The customer ID for which the call is made.")]
public
long
CustomerId
{
get
;
set
;
}
/// <summary>
/// The ad group ID that contains the ad.
/// </summary>
[Option("adGroupId", Required = true, HelpText =
"The ad group ID that contains the ad.")]
public
long
AdGroupId
{
get
;
set
;
}
/// <summary>
/// AdGroupAdService.
/// </summary>
[Option("adId", Required = true, HelpText =
"AdGroupAdService.")]
public
long
AdId
{
get
;
set
;
}
}
/// <summary>
/// Main method, to run this code example as a standalone application.
/// </summary>
/// <param name="args">The command line arguments.</param>
public
static
void
Main
(
string
[]
args
)
{
Options
options
=
ExampleUtilities
.
ParseCommandLine<Options>
(
args
);
PauseAd
codeExample
=
new
PauseAd
();
Console
.
WriteLine
(
codeExample
.
Description
);
codeExample
.
Run
(
new
GoogleAdsClient
(),
options
.
CustomerId
,
options
.
AdGroupId
,
options
.
AdId
);
}
/// <summary>
/// Returns a description about the code example.
/// </summary>
public
override
string
Description
=
> "This code example pauses a given ad. To list all ads, run GetExpandedTextAds.cs."
;
/// <summary>
/// Runs the code example.
/// </summary>
/// <param name="client">The Google Ads client.</param>
/// <param name="customerId">The customer ID for which the call is made.</param>
/// <param name="adGroupId">The ad group ID that contains the ad.</param>
/// <param name="adId">AdGroupAdService</param>
public
void
Run
(
GoogleAdsClient
client
,
long
customerId
,
long
adGroupId
,
long
adId
)
{
// Get the AdGroupAdService.
AdGroupAdServiceClient
adGroupAdService
=
client
.
GetService
(
Services
.
V22
.
AdGroupAdService
);
// Create the ad group ad.
AdGroupAd
adGroupAd
=
new
AdGroupAd
{
ResourceName
=
ResourceNames
.
AdGroupAd
(
customerId
,
adGroupId
,
adId
),
Status
=
AdGroupAdStatus
.
Paused
};
// Create the operation.
AdGroupAdOperation
operation
=
new
AdGroupAdOperation
{
// Set the Update field to the ad group ad object.
Update
=
adGroupAd
,
// Use the FieldMasks utility to set the UpdateMask field to a list of all
// modified fields of the ad group ad.
UpdateMask
=
FieldMasks
.
AllSetFieldsOf
(
adGroupAd
)
};
try
{
// Update the ad.
MutateAdGroupAdsResponse
response
=
adGroupAdService
.
MutateAdGroupAds
(
customerId
.
ToString
(),
new
AdGroupAdOperation
[]
{
operation
});
// Display the results.
foreach
(
MutateAdGroupAdResult
result
in
response
.
Results
)
{
Console
.
WriteLine
(
$"Ad with resource name = {result.ResourceName} was "
+
"paused."
);
}
}
catch
(
GoogleAdsException
e
)
{
Console
.
WriteLine
(
"Failure:"
);
Console
.
WriteLine
(
$"Message: {e.Message}"
);
Console
.
WriteLine
(
$"Failure: {e.Failure}"
);
Console
.
WriteLine
(
$"Request ID: {e.RequestId}"
);
throw
;
}
}
}
}
PHP
< ?php
/**
* Copyright 2018 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
namespace Google\Ads\GoogleAds\Examples\BasicOperations;
require __DIR__ . '/../../vendor/autoload.php';
use GetOpt\GetOpt;
use Google\Ads\GoogleAds\Examples\Utils\ArgumentNames;
use Google\Ads\GoogleAds\Examples\Utils\ArgumentParser;
use Google\Ads\GoogleAds\Lib\V22\GoogleAdsClient;
use Google\Ads\GoogleAds\Lib\V22\GoogleAdsClientBuilder;
use Google\Ads\GoogleAds\Lib\V22\GoogleAdsException;
use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\Util\FieldMasks;
use Google\Ads\GoogleAds\Util\V22\ResourceNames;
use Google\Ads\GoogleAds\V22\Enums\AdGroupAdStatusEnum\AdGroupAdStatus;
use Google\Ads\GoogleAds\V22\Errors\GoogleAdsError;
use Google\Ads\GoogleAds\V22\Resources\AdGroupAd;
use Google\Ads\GoogleAds\V22\Services\AdGroupAdOperation;
use Google\Ads\GoogleAds\V22\Services\MutateAdGroupAdsRequest;
use Google\ApiCore\ApiException;
/**
* This example changes the status of a given ad to `PAUSED`. To get ad groups, run GetAdGroups.php.
*/
class PauseAd
{
private const CUSTOMER_ID = 'INSERT_CUSTOMER_ID_HERE';
private const AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE';
private const AD_ID = 'INSERT_AD_ID_HERE';
public static function main()
{
// Either pass the required parameters for this example on the command line, or insert them
// into the constants above.
$options = (new ArgumentParser())->parseCommandArguments([
ArgumentNames::CUSTOMER_ID => GetOpt::REQUIRED_ARGUMENT,
ArgumentNames::AD_GROUP_ID => GetOpt::REQUIRED_ARGUMENT,
ArgumentNames::AD_ID => GetOpt::REQUIRED_ARGUMENT
]);
// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();
// Construct a Google Ads client configured from a properties file and the
// OAuth2 credentials above.
$googleAdsClient = (new GoogleAdsClientBuilder())->fromFile()
->withOAuth2Credential($oAuth2Credential)
->build();
try {
self::runExample(
$googleAdsClient,
$options[ArgumentNames::CUSTOMER_ID] ?: self::CUSTOMER_ID,
$options[ArgumentNames::AD_GROUP_ID] ?: self::AD_GROUP_ID,
$options[ArgumentNames::AD_ID] ?: self::AD_ID
);
} catch (GoogleAdsException $googleAdsException) {
printf(
"Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
$googleAdsException->getRequestId(),
PHP_EOL,
PHP_EOL
);
foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() as $error) {
/** @var GoogleAdsError $error */
printf(
"\t%s: %s%s",
$error->getErrorCode()->getErrorCode(),
$error->getMessage(),
PHP_EOL
);
}
exit(1);
} catch (ApiException $apiException) {
printf(
"ApiException was thrown with message '%s'.%s",
$apiException->getMessage(),
PHP_EOL
);
exit(1);
}
}
/**
* Runs the example.
*
* @param GoogleAdsClient $googleAdsClient the Google Ads API client
* @param int $customerId the customer ID
* @param int $adGroupId the ad group ID that the ad group ad belongs to
* @param int $adId the ID of the ad to pause
*/
public static function runExample(
GoogleAdsClient $googleAdsClient,
int $customerId,
int $adGroupId,
int $adId
) {
// Creates ad group ad resource name.
$adGroupAdResourceName = ResourceNames::forAdGroupAd($customerId, $adGroupId, $adId);
// Creates an ad and sets its status to PAUSED.
$adGroupAd = new AdGroupAd();
$adGroupAd->setResourceName($adGroupAdResourceName);
$adGroupAd->setStatus(AdGroupAdStatus::PAUSED);
// Constructs an operation that will pause the ad with the specified resource name,
// using the FieldMasks utility to derive the update mask. This mask tells the Google Ads
// API which attributes of the ad group you want to change.
$adGroupAdOperation = new AdGroupAdOperation();
$adGroupAdOperation->setUpdate($adGroupAd);
$adGroupAdOperation->setUpdateMask(FieldMasks::allSetFieldsOf($adGroupAd));
// Issues a mutate request to pause the ad group ad.
$adGroupAdServiceClient = $googleAdsClient->getAdGroupAdServiceClient();
$response = $adGroupAdServiceClient->mutateAdGroupAds(MutateAdGroupAdsRequest::build(
$customerId,
[$adGroupAdOperation]
));
// Prints the resource name of the paused ad group ad.
/** @var AdGroupAd $pausedAdGroupAd */
$pausedAdGroupAd = $response->getResults()[0];
printf(
"Ad group ad with resource name: '%s' is paused.%s",
$pausedAdGroupAd->getResourceName(),
PHP_EOL
);
}
}
PauseAd::main();
Python
#!/usr/bin/env python
# Copyright 2018 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""This example pauses an ad."""
import
argparse
import
sys
from
typing
import
List
from
google.api_core
import
protobuf_helpers
from
google.ads.googleads.client
import
GoogleAdsClient
from
google.ads.googleads.errors
import
GoogleAdsException
from
google.ads.googleads.v22.resources.types.ad_group_ad
import
AdGroupAd
from
google.ads.googleads.v22.services.services.ad_group_ad_service
import
(
AdGroupAdServiceClient
,
)
from
google.ads.googleads.v22.services.types.ad_group_ad_service
import
(
AdGroupAdOperation
,
MutateAdGroupAdsResponse
,
)
def
main
(
client
:
GoogleAdsClient
,
customer_id
:
str
,
ad_group_id
:
str
,
ad_id
:
str
,
)
-
> None
:
ad_group_ad_service
:
AdGroupAdServiceClient
=
client
.
get_service
(
"AdGroupAdService"
)
ad_group_ad_operation
:
AdGroupAdOperation
=
client
.
get_type
(
"AdGroupAdOperation"
)
ad_group_ad
:
AdGroupAd
=
ad_group_ad_operation
.
update
ad_group_ad
.
resource_name
=
ad_group_ad_service
.
ad_group_ad_path
(
customer_id
,
ad_group_id
,
ad_id
)
ad_group_ad
.
status
=
client
.
enums
.
AdGroupAdStatusEnum
.
PAUSED
client
.
copy_from
(
ad_group_ad_operation
.
update_mask
,
protobuf_helpers
.
field_mask
(
None
,
ad_group_ad
.
_pb
),
)
operations
:
List
[
AdGroupAdOperation
]
=
[
ad_group_ad_operation
]
ad_group_ad_response
:
MutateAdGroupAdsResponse
=
(
ad_group_ad_service
.
mutate_ad_group_ads
(
customer_id
=
customer_id
,
operations
=
operations
,
)
)
print
(
f
"Paused ad group ad
{
ad_group_ad_response
.
results
[
0
]
.
resource_name
}
."
)
if
__name__
==
"__main__"
:
parser
=
argparse
.
ArgumentParser
(
description
=
(
"Pauses an ad in the specified customer's ad group."
)
)
# The following argument(s) should be provided to run the example.
parser
.
add_argument
(
"-c"
,
"--customer_id"
,
type
=
str
,
required
=
True
,
help
=
"The Google Ads customer ID."
,
)
parser
.
add_argument
(
"-a"
,
"--ad_group_id"
,
type
=
str
,
required
=
True
,
help
=
"The ad group ID."
)
parser
.
add_argument
(
"-i"
,
"--ad_id"
,
type
=
str
,
required
=
True
,
help
=
"The ad ID."
)
args
:
argparse
.
Namespace
=
parser
.
parse_args
()
# GoogleAdsClient will read the google-ads.yaml configuration file in the
# home directory if none is specified.
googleads_client
:
GoogleAdsClient
=
GoogleAdsClient
.
load_from_storage
(
version
=
"v22"
)
try
:
main
(
googleads_client
,
args
.
customer_id
,
args
.
ad_group_id
,
args
.
ad_id
)
except
GoogleAdsException
as
ex
:
print
(
f
'Request with ID "
{
ex
.
request_id
}
" failed with status '
f
'"
{
ex
.
error
.
code
()
.
name
}
" and includes the following errors:'
)
for
error
in
ex
.
failure
.
errors
:
print
(
f
'
\t
Error with message "
{
error
.
message
}
".'
)
if
error
.
location
:
for
field_path_element
in
error
.
location
.
field_path_elements
:
print
(
f
"
\t\t
On field:
{
field_path_element
.
field_name
}
"
)
sys
.
exit
(
1
)
Ruby
#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright 2018 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# This example pauses an ad.
require
'optparse'
require
'google/ads/google_ads'
def
pause_ad
(
customer_id
,
ad_group_id
,
ad_id
)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client
=
Google
::
Ads
::
GoogleAds
::
GoogleAdsClient
.
new
aga_resource_name
=
client
.
path
.
ad_group_ad
(
customer_id
,
ad_group_id
,
ad_id
)
operation
=
client
.
operation
.
update_resource
.
ad_group_ad
(
aga_resource_name
)
do
|
aga
|
aga
.
status
=
:PAUSED
end
response
=
client
.
service
.
ad_group_ad
.
mutate_ad_group_ads
(
customer_id
:
customer_id
,
operations
:
[
operation
]
,
)
puts
"Paused ad
#{
response
.
results
.
first
.
resource_name
}
"
end
if
__FILE__
==
$PROGRAM_NAME
options
=
{}
# The following parameter(s) should be provided to run the example. You can
# either specify these by changing the INSERT_XXX_ID_HERE values below, or on
# the command line.
#
# Parameters passed on the command line will override any parameters set in
# code.
#
# Running the example with -h will print the command line usage.
options
[
:customer_id
]
=
'INSERT_CUSTOMER_ID_HERE'
options
[
:ad_group_id
]
=
'INSERT_AD_GROUP_ID_HERE'
options
[
:ad_id
]
=
'INSERT_AD_ID_HERE'
OptionParser
.
new
do
|
opts
|
opts
.
banner
=
sprintf
(
'Usage: %s [options]'
,
File
.
basename
(
__FILE__
))
opts
.
separator
''
opts
.
separator
'Options:'
opts
.
on
(
'-C'
,
'--customer-id CUSTOMER-ID'
,
String
,
'Customer ID'
)
do
|
v
|
options
[
:customer_id
]
=
v
end
opts
.
on
(
'-A'
,
'--ad-group-id AD-GROUP-ID'
,
String
,
'Ad Group ID'
)
do
|
v
|
options
[
:ad_group_id
]
=
v
end
opts
.
on
(
'-a'
,
'--ad-id AD-ID'
,
String
,
'Ad ID'
)
do
|
v
|
options
[
:ad_id
]
=
v
end
opts
.
separator
''
opts
.
separator
'Help:'
opts
.
on_tail
(
'-h'
,
'--help'
,
'Show this message'
)
do
puts
opts
exit
end
end
.
parse!
begin
pause_ad
(
options
.
fetch
(
:customer_id
)
.
tr
(
"-"
,
""
),
options
[
:ad_group_id
]
,
options
[
:ad_id
]
)
rescue
Google
::
Ads
::
GoogleAds
::
Errors
::
GoogleAdsError
=
> e
e
.
failure
.
errors
.
each
do
|
error
|
STDERR
.
printf
(
"Error with message: %s
\n
"
,
error
.
message
)
if
error
.
location
error
.
location
.
field_path_elements
.
each
do
|
field_path_element
|
STDERR
.
printf
(
"
\t
On field: %s
\n
"
,
field_path_element
.
field_name
)
end
end
error
.
error_code
.
to_h
.
each
do
|
k
,
v
|
next
if
v
==
:UNSPECIFIED
STDERR
.
printf
(
"
\t
Type: %s
\n\t
Code: %s
\n
"
,
k
,
v
)
end
end
raise
end
end
Perl
#!/usr/bin/perl -w
#
# Copyright 2019, Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# This example changes the status of a given ad to PAUSED.
use
strict
;
use
warnings
;
use
utf8
;
use
FindBin
qw($Bin)
;
use
lib
"$Bin/../../lib"
;
use
Google::Ads::GoogleAds::Client
;
use
Google::Ads::GoogleAds::Utils::GoogleAdsHelper
;
use
Google::Ads::GoogleAds::Utils::FieldMasks
;
use
Google::Ads::GoogleAds::V22::Resources::AdGroupAd
;
use
Google::Ads::GoogleAds::V22::Enums::AdGroupAdStatusEnum
qw(PAUSED)
;
use
Google::Ads::GoogleAds::V22::Services::AdGroupAdService::AdGroupAdOperation
;
use
Google::Ads::GoogleAds::V22::Utils::ResourceNames
;
use
Getopt::Long
qw(:config auto_help)
;
use
Pod::Usage
;
use
Cwd
qw(abs_path)
;
# The following parameter(s) should be provided to run the example. You can
# either specify these by changing the INSERT_XXX_ID_HERE values below, or on
# the command line.
#
# Parameters passed on the command line will override any parameters set in
# code.
#
# Running the example with -h will print the command line usage.
my
$customer_id
=
"INSERT_CUSTOMER_ID_HERE"
;
my
$ad_group_id
=
"INSERT_AD_GROUP_ID_HERE"
;
my
$ad_id
=
"INSERT_AD_ID_HERE"
;
sub
pause_ad
{
my
(
$api_client
,
$customer_id
,
$ad_group_id
,
$ad_id
)
=
@_
;
# Create an ad group ad with its status set to PAUSED.
my
$ad_group_ad
=
Google::Ads::GoogleAds::V22::Resources::
AdGroupAd
-
> new
({
resourceName
=
> Google::Ads::GoogleAds::V22::Utils::ResourceNames::
ad_group_ad
(
$customer_id
,
$ad_group_id
,
$ad_id
),
status
=
> PAUSED
});
# Create an ad group ad operation for update, using the FieldMasks utility
# to derive the update mask.
my
$ad_group_ad_operation
=
Google::Ads::GoogleAds::V22::Services::AdGroupAdService::
AdGroupAdOperation
-
> new
({
update
=
> $ad_group_ad
,
updateMask
=
> all_set_fields_of
(
$ad_group_ad
)});
# Update the ad group ad.
my
$ad_group_ads_response
=
$api_client
-
> AdGroupAdService
()
-
> mutate
({
customerId
=
> $customer_id
,
operations
=
> [
$ad_group_ad_operation
]});
printf
"Ad with resource name '%s' is paused.\n"
,
$ad_group_ads_response
-
> {
results
}[
0
]{
resourceName
};
return
1
;
}
# Don't run the example if the file is being included.
if
(
abs_path
(
$0
)
ne
abs_path
(
__FILE__
))
{
return
1
;
}
# Get Google Ads Client, credentials will be read from ~/googleads.properties.
my
$api_client
=
Google::Ads::GoogleAds::
Client
-
> new
();
# By default examples are set to die on any server returned fault.
$api_client
-
> set_die_on_faults
(
1
);
# Parameters passed on the command line will override any parameters set in code.
GetOptions
(
"customer_id=s"
=
> \
$customer_id
,
"ad_group_id=i"
=
> \
$ad_group_id
,
"ad_id=i"
=
> \
$ad_id
);
# Print the help message if the parameters are not initialized in the code nor
# in the command line.
pod2usage
(
2
)
if
not
check_params
(
$customer_id
,
$ad_group_id
,
$ad_id
);
# Call the example.
pause_ad
(
$api_client
,
$customer_id
=~
s/-//g
r
,
$ad_group_id
,
$ad_id
);
=pod
=head1 NAME
pause_ad
=head1 DESCRIPTION
This example changes the status of a given ad to PAUSED.
=head1 SYNOPSIS
pause_ad.pl [options]
-help Show the help message.
-customer_id The Google Ads customer ID.
-ad_group_id The ad group ID.
-ad_id The ad ID.
=cut
Send feedback
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License
, and code samples are licensed under the Apache 2.0 License
. For details, see the Google Developers Site Policies
. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-11-05 UTC.
Need to tell us more?
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-11-05 UTC."],[],[]]
