Java
// Copyright 2020 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.remarketing ; 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.v21.enums.ConversionAdjustmentTypeEnum.ConversionAdjustmentType ; import com.google.ads.googleads.v21.errors.GoogleAdsError ; import com.google.ads.googleads.v21.errors.GoogleAdsException ; import com.google.ads.googleads.v21.errors.GoogleAdsFailure ; import com.google.ads.googleads.v21.services.ConversionAdjustment ; import com.google.ads.googleads.v21.services.ConversionAdjustmentResult ; import com.google.ads.googleads.v21.services.ConversionAdjustmentUploadServiceClient ; import com.google.ads.googleads.v21.services.RestatementValue ; import com.google.ads.googleads.v21.services.UploadConversionAdjustmentsRequest ; import com.google.ads.googleads.v21.services.UploadConversionAdjustmentsResponse ; import com.google.ads.googleads.v21.utils.ErrorUtils ; import com.google.ads.googleads.v21.utils.ResourceNames ; import com.google.protobuf.InvalidProtocolBufferException ; import com.google.protobuf.util.JsonFormat ; import com.google.protobuf.util.JsonFormat.Printer ; import java.io.FileNotFoundException ; import java.io.IOException ; import javax.annotation.Nullable ; /** * Imports conversion adjustments for conversions that already exist. To set up a conversion action, * run the AddConversionAction.java example. */ public class UploadConversionAdjustment { private static class UploadConversionAdjustmentParams extends CodeSampleParams { @Parameter ( names = ArgumentNames . CUSTOMER_ID , required = true ) private long customerId ; @Parameter ( names = ArgumentNames . CONVERSION_ACTION_ID , required = true ) private long conversionActionId ; @Parameter ( names = ArgumentNames . ORDER_ID , required = true , description = "The transaction ID of the conversion to adjust. Required if the conversion being" + " adjusted meets the criteria described at" + " https://developers.google.com/google-ads/api/docs/conversions/upload-adjustments#requirements." ) private String orderId ; @Parameter ( names = ArgumentNames . ADJUSTMENT_TYPE , required = true , description = "RETRACTION negates a conversion, and RESTATEMENT changes the value of a conversion." ) private String adjustmentType ; @Parameter ( names = ArgumentNames . ADJUSTMENT_DATE_TIME , required = true , description = "The date time at which the adjustment occurred. " + "Must be after the click time, and must include the time zone offset. " + "The format is 'yyyy-mm-dd hh:mm:ss+|-hh:mm', e.g. '2019-01-01 12:32:45-08:00'." ) private String adjustmentDateTime ; @Parameter ( names = ArgumentNames . RESTATEMENT_VALUE , description = "The updated value of the conversion. Only applicable for ADJUSTMENT_TYPE of" + " RESTATEMENT." ) private Float restatementValue ; } public static void main ( String [] args ) throws InvalidProtocolBufferException { UploadConversionAdjustmentParams params = new UploadConversionAdjustmentParams (); 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 . conversionActionId = Long . parseLong ( "INSERT_CONVERSION_ACTION_ID_HERE" ); params . orderId = "INSERT_ORDER_ID_HERE" ; params . adjustmentType = "INSERT_ADJUSTMENT_TYPE_HERE" ; params . adjustmentDateTime = "INSERT_ADJUSTMENT_DATE_TIME_HERE" ; // Optional: Specify a restatement value for adjustments of type RESTATEMENT. params . restatementValue = null ; } 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 UploadConversionAdjustment () . runExample ( googleAdsClient , params . customerId , params . conversionActionId , params . orderId , params . adjustmentType , params . adjustmentDateTime , params . restatementValue ); } 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 conversionActionId conversion action ID associated with this conversion. * @param orderId the orderId for the conversion. Strongly recommended instead of using {@code * gclid} and {@code conversionDateTime}. * @param adjustmentType the type of adjustment, e.g. RETRACTION, RESTATEMENT. * @param adjustmentDateTime date and time of the adjustment. * @param restatementValue the adjusted value for adjustment type RESTATEMENT. */ private void runExample ( GoogleAdsClient googleAdsClient , long customerId , long conversionActionId , String orderId , String adjustmentType , String adjustmentDateTime , @Nullable Float restatementValue ) throws InvalidProtocolBufferException { // Gets the conversion adjustment enum value from the adjustmentType String. ConversionAdjustmentType conversionAdjustmentType = ConversionAdjustmentType . valueOf ( adjustmentType ); // Applies the conversion adjustment to the existing conversion. ConversionAdjustment conversionAdjustment = ConversionAdjustment . newBuilder () . setConversionAction ( ResourceNames . conversionAction ( customerId , conversionActionId )) . setAdjustmentType ( conversionAdjustmentType ) // Sets the orderId to identify the conversion to adjust. . setOrderId ( orderId ) // As an alternative to setting orderId, you can provide a GclidDateTimePair, but // setting orderId instead is strongly recommended. // .setGclidDateTimePair( // GclidDateTimePair.newBuilder() // .setGclid(gclid) // .setConversionDateTime(conversionDateTime) // .build()) . setAdjustmentDateTime ( adjustmentDateTime ) . build (); // Sets adjusted value for adjustment type RESTATEMENT. if ( restatementValue != null && conversionAdjustmentType == ConversionAdjustmentType . RESTATEMENT ) { conversionAdjustment = conversionAdjustment . toBuilder () . setRestatementValue ( RestatementValue . newBuilder (). setAdjustedValue ( restatementValue ). build ()) . build (); } // Creates the conversion upload service client. try ( ConversionAdjustmentUploadServiceClient conversionUploadServiceClient = googleAdsClient . getLatestVersion (). createConversionAdjustmentUploadServiceClient ()) { // Uploads the click conversion. Partial failure should always be set to true. UploadConversionAdjustmentsRequest request = UploadConversionAdjustmentsRequest . newBuilder () . setCustomerId ( Long . toString ( customerId )) // Enables partial failure (must be true). . setPartialFailure ( true ) . addConversionAdjustments ( conversionAdjustment ) . build (); UploadConversionAdjustmentsResponse response = conversionUploadServiceClient . uploadConversionAdjustments ( request ); // Extracts the partial failure error if present on the response. ErrorUtils errorUtils = ErrorUtils . getInstance (); GoogleAdsFailure googleAdsFailure = response . hasPartialFailureError () ? errorUtils . getGoogleAdsFailure ( response . getPartialFailureError ()) : null ; // Constructs a protocol buffer printer that will print error details in a concise format. final Printer errorPrinter = JsonFormat . printer (). omittingInsignificantWhitespace (); // Prints the results for each adjustment, including any partial errors returned. for ( int opIndex = 0 ; opIndex < request . getConversionAdjustmentsCount (); opIndex ++ ) { ConversionAdjustmentResult result = response . getResults ( opIndex ); if ( errorUtils . isPartialFailureResult ( result )) { // The operation failed. Prints the error details. for ( GoogleAdsError googleAdsError : errorUtils . getGoogleAdsErrors ( opIndex , googleAdsFailure )) { System . out . printf ( "%4d: Partial failure occurred: %s%n" , opIndex , errorPrinter . print ( googleAdsError )); } } else { System . out . printf ( "%4d: Uploaded conversion adjustment for conversion action '%s' and order ID '%s'.%n" , opIndex , result . getConversionAction (), result . getOrderId ()); } } } } }
C#
// Copyright 2020 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.GoogleAds.Lib ; using Google.Ads.GoogleAds.V21.Errors ; using Google.Ads.GoogleAds.V21.Resources ; using Google.Ads.GoogleAds.V21.Services ; using System ; using System.Collections.Generic ; using static Google . Ads . GoogleAds . V21 . Enums . ConversionAdjustmentTypeEnum . Types ; namespace Google.Ads.GoogleAds.Examples.V21 { /// <summary> /// This code example imports conversion adjustments for conversions that already exist. /// To set up a conversion action, run AddConversionAction.cs. /// </summary> public class UploadConversionAdjustment : ExampleBase { /// <summary> /// Command line options for running the <see cref="UploadConversionAdjustment"/> example. /// </summary> public class Options : OptionsBase { /// <summary> /// The Google Ads customer ID for which the conversion action is added. /// </summary> [Option("customerId", Required = true, HelpText = "The Google Ads customer ID for which the conversion action is added.")] public long CustomerId { get ; set ; } /// <summary> /// ID of the conversion action for which adjustments are uploaded. /// </summary> [Option("conversionActionId", Required = true, HelpText = "ID of the conversion action for which adjustments are uploaded.")] public long ConversionActionId { get ; set ; } /// <summary> /// The type of adjustment. /// </summary> [Option("adjustmentType", Required = true, HelpText = "The type of adjustment.")] public ConversionAdjustmentType AdjustmentType { get ; set ; } /// <summary> /// The transaction ID of the conversion to adjust. Required if the conversion being /// adjusted meets the criteria described at /// https://developers.google.com/google-ads/api/docs/conversions/upload-adjustments#requirements. /// </summary> [Option("orderId", Required = true, HelpText = "The transaction ID of the conversion to adjust. Required if the conversion " + "being adjusted meets the criteria described at " + "https://developers.google.com/google-ads/api/docs/conversions/upload-adjustments#requirements." )] public string OrderId { get ; set ; } /// <summary> /// The adjustment date and time. /// </summary> [Option("adjustmentDateTime", Required = true, HelpText = "The adjustment date and time.")] public string AdjustmentDateTime { get ; set ; } /// <summary> /// The restatement value. /// </summary> [Option("restatementValue", Required = true, HelpText = "The restatement value.")] public double? RestatementValue { 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 ); UploadConversionAdjustment codeExample = new UploadConversionAdjustment (); Console . WriteLine ( codeExample . Description ); codeExample . Run ( new GoogleAdsClient (), options . CustomerId , options . ConversionActionId , options . OrderId , options . AdjustmentDateTime , options . AdjustmentType , options . RestatementValue ); } /// <summary> /// Returns a description about the code example. /// </summary> public override string Description = > "This code example imports conversion adjustments for conversions that already " + "exist. To set up a conversion action, run AddConversionAction.cs." ; /// <summary> /// Runs the code example. /// </summary> /// <param name="client">The Google Ads client.</param> /// <param name="customerId">The Google Ads customer ID for which the conversion action is /// added.</param> /// <param name="conversionActionId">ID of the conversion action for which adjustments are /// uploaded.</param> /// <param name="adjustmentType">The type of adjustment.</param> /// <param name="orderId">The order ID for the conversion. Strongly recommended instead /// of using GCLID and conversionDateTime.</param> /// <param name="adjustmentDateTime">The adjustment date and time.</param> /// <param name="restatementValue">The restatement value.</param> public void Run ( GoogleAdsClient client , long customerId , long conversionActionId , string orderId , string adjustmentDateTime , ConversionAdjustmentType adjustmentType , double? restatementValue ) { // Get the ConversionAdjustmentUploadService. ConversionAdjustmentUploadServiceClient conversionAdjustmentUploadService = client . GetService ( Services . V21 . ConversionAdjustmentUploadService ); // Associate conversion adjustments with the existing conversion action. ConversionAdjustment conversionAdjustment = new ConversionAdjustment () { ConversionAction = ResourceNames . ConversionAction ( customerId , conversionActionId ), AdjustmentType = adjustmentType , // Sets the orderId to identify the conversion to adjust. OrderId = orderId , // As an alternative to setting orderId, you can provide a GclidDateTimePair, // but setting orderId instead is strongly recommended. //GclidDateTimePair = new GclidDateTimePair() //{ // Gclid = gclid, // ConversionDateTime = conversionDateTime, //}, AdjustmentDateTime = adjustmentDateTime , }; // Set adjusted value for adjustment type RESTATEMENT. if ( adjustmentType == ConversionAdjustmentType . Restatement ) { conversionAdjustment . RestatementValue = new RestatementValue () { AdjustedValue = restatementValue . Value }; } try { // Issue a request to upload the conversion adjustment. UploadConversionAdjustmentsResponse response = conversionAdjustmentUploadService . UploadConversionAdjustments ( new UploadConversionAdjustmentsRequest () { CustomerId = customerId . ToString (), ConversionAdjustments = { conversionAdjustment }, // Enables partial failure (must be true). PartialFailure = true , ValidateOnly = false }); // Prints any partial errors returned. // To review the overall health of your recent uploads, see: // https://developers.google.com/google-ads/api/docs/conversions/upload-summaries if ( response . PartialFailureError != null ) { // Extracts the partial failure from the response status. GoogleAdsFailure partialFailure = response . PartialFailure ; Console . WriteLine ( $"{partialFailure.Errors.Count} partial failure error(s) " + $"occurred" ); } else { ConversionAdjustmentResult result = response . Results [ 0 ]; // Print the result. Console . WriteLine ( $"Uploaded conversion adjustment value of" + $" '{result.ConversionAction}' for Google Click ID " + $"'{result.GclidDateTimePair.Gclid}'" ); } } 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 2020 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\Remarketing; 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\OAuth2TokenBuilder; use Google\Ads\GoogleAds\Lib\V21\GoogleAdsClient; use Google\Ads\GoogleAds\Lib\V21\GoogleAdsClientBuilder; use Google\Ads\GoogleAds\Lib\V21\GoogleAdsException; use Google\Ads\GoogleAds\Util\V21\ResourceNames; use Google\Ads\GoogleAds\V21\Enums\ConversionAdjustmentTypeEnum\ConversionAdjustmentType; use Google\Ads\GoogleAds\V21\Errors\GoogleAdsError; use Google\Ads\GoogleAds\V21\Services\ConversionAdjustment; use Google\Ads\GoogleAds\V21\Services\ConversionAdjustmentResult; use Google\Ads\GoogleAds\V21\Services\GclidDateTimePair; use Google\Ads\GoogleAds\V21\Services\RestatementValue; use Google\Ads\GoogleAds\V21\Services\UploadConversionAdjustmentsRequest; use Google\ApiCore\ApiException; /** * This example imports conversion adjustments for conversions that already exist. * To set up a conversion action, run the AddConversionAction.php example. */ class UploadConversionAdjustment { private const CUSTOMER_ID = 'INSERT_CUSTOMER_ID_HERE'; private const CONVERSION_ACTION_ID = 'INSERT_CONVERSION_ACTION_ID_HERE'; // The transaction ID of the conversion to adjust. Required if the conversion being adjusted // meets the criteria described at // https://developers.google.com/google-ads/api/docs/conversions/upload-adjustments#requirements. private const ORDER_ID = 'INSERT_ORDER_ID_HERE'; // RETRACTION negates a conversion, and RESTATEMENT changes the value of a conversion. private const ADJUSTMENT_TYPE = "INSERT_ADJUSTMENT_TYPE_HERE"; // The adjustment date time in "yyyy-mm-dd hh:mm:ss+|-hh:mm" format. private const ADJUSTMENT_DATE_TIME = "INSERT_ADJUSTMENT_DATE_TIME_HERE"; // Optional: Specify an adjusted value below for adjustment type RESTATEMENT. // This value will be ignored if you specify RETRACTION as adjustment type. private const RESTATEMENT_VALUE = null; 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::CONVERSION_ACTION_ID => GetOpt::REQUIRED_ARGUMENT, ArgumentNames::ORDER_ID => GetOpt::REQUIRED_ARGUMENT, ArgumentNames::ADJUSTMENT_TYPE => GetOpt::REQUIRED_ARGUMENT, ArgumentNames::ADJUSTMENT_DATE_TIME => GetOpt::REQUIRED_ARGUMENT, ArgumentNames::RESTATEMENT_VALUE => GetOpt::OPTIONAL_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::CONVERSION_ACTION_ID] ?: self::CONVERSION_ACTION_ID, $options[ArgumentNames::ORDER_ID] ?: self::ORDER_ID, $options[ArgumentNames::ADJUSTMENT_TYPE] ?: self::ADJUSTMENT_TYPE, $options[ArgumentNames::ADJUSTMENT_DATE_TIME] ?: self::ADJUSTMENT_DATE_TIME, $options[ArgumentNames::RESTATEMENT_VALUE] ?: self::RESTATEMENT_VALUE ); } 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 $conversionActionId the ID of the conversion action to upload adjustment to * @param string $orderId the order ID for the conversion. Strongly recommended instead of * using GCLID and conversion date time * @param string $adjustmentType the type of adjustment, e.g. RETRACTION, RESTATEMENT * @param string $adjustmentDateTime the date and time of the adjustment. * The format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", e.g. “2019-01-01 12:32:45-08:00” * @param float|null $restatementValue the adjusted value for adjustment type RESTATEMENT */ public static function runExample( GoogleAdsClient $googleAdsClient, int $customerId, int $conversionActionId, string $orderId, string $adjustmentType, string $adjustmentDateTime, ?float $restatementValue ) { $conversionAdjustmentType = ConversionAdjustmentType::value($adjustmentType); // Applies the conversion adjustment to the existing conversion. $conversionAdjustment = new ConversionAdjustment([ 'conversion_action' = > ResourceNames::forConversionAction($customerId, $conversionActionId), 'adjustment_type' => $conversionAdjustmentType, // Sets the orderId to identify the conversion to adjust. 'order_id' => $orderId, // As an alternative to setting orderId, you can provide a 'gclid_date_time_pair', but // setting 'order_id' instead is strongly recommended. // 'conversion_date_time' must be in "yyyy-mm-dd hh:mm:ss+|-hh:mm" format. /* 'gclid_date_time_pair' => new GclidDateTimePair([ 'gclid' => 'INSERT_YOUR_GCLID_HERE', 'conversion_date_time' => 'INSERT_YOUR_CONVERSION_DATE_TIME_HERE' ]), */ 'adjustment_date_time' => $adjustmentDateTime ]); // Sets adjusted value for adjustment type RESTATEMENT. if ( $restatementValue !== null && $conversionAdjustmentType === ConversionAdjustmentType::RESTATEMENT ) { $conversionAdjustment->setRestatementValue(new RestatementValue([ 'adjusted_value' => $restatementValue ])); } // Issues a request to upload the conversion adjustment. $conversionAdjustmentUploadServiceClient = $googleAdsClient->getConversionAdjustmentUploadServiceClient(); $response = $conversionAdjustmentUploadServiceClient->uploadConversionAdjustments( // Enables partial failure (must be true). UploadConversionAdjustmentsRequest::build($customerId, [$conversionAdjustment], true) ); // Prints the status message if any partial failure error is returned. // Note: The details of each partial failure error are not printed here, you can refer to // the example HandlePartialFailure.php to learn more. if ($response->hasPartialFailureError()) { printf( "Partial failures occurred: '%s'.%s", $response->getPartialFailureError()->getMessage(), PHP_EOL ); } else { // Prints the result if exists. /** @var ConversionAdjustmentResult $uploadedConversionAdjustment */ $uploadedConversionAdjustment = $response->getResults()[0]; printf( "Uploaded conversion adjustment of '%s' for order ID '%s'.%s", $uploadedConversionAdjustment->getConversionAction(), $uploadedConversionAdjustment->getOrderId(), PHP_EOL ); } } } UploadConversionAdjustment::main();
Python
#!/usr/bin/env python # Copyright 2020 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 imports conversion adjustments for existing conversions. To set up a conversion action, run the add_conversion_action.py example. """ import argparse import sys from typing import Optional , Iterable from google.protobuf.any_pb2 import Any from google.ads.googleads.client import GoogleAdsClient from google.ads.googleads.errors import GoogleAdsException from google.ads.googleads.v21.enums.types.conversion_adjustment_type import ( ConversionAdjustmentTypeEnum , ) from google.ads.googleads.v21.errors.types.errors import ( GoogleAdsError , GoogleAdsFailure , ) from google.ads.googleads.v21.services.services.conversion_action_service import ( ConversionActionServiceClient , ) from google.ads.googleads.v21.services.services.conversion_adjustment_upload_service import ( ConversionAdjustmentUploadServiceClient , ) from google.ads.googleads.v21.services.types.conversion_adjustment_upload_service import ( ConversionAdjustment , ConversionAdjustmentResult , UploadConversionAdjustmentsRequest , UploadConversionAdjustmentsResponse , ) def main ( client : GoogleAdsClient , customer_id : str , conversion_action_id : str , adjustment_type : str , order_id : str , adjustment_date_time : str , restatement_value : Optional [ str ] = None , ) - > None : """The main method that creates all necessary entities for the example. Args: client: an initialized GoogleAdsClient instance. customer_id: a client customer ID. conversion_action_id: the ID of the conversion action to upload the adjustment to. adjustment_type: the adjustment type, e.g. " "RETRACTION, RESTATEMENT. order_id: the transaction ID of the conversion to adjust. Strongly recommended instead of using gclid and conversion_date_time. adjustment_date_time: the date and time of the adjustment. restatement_value: the adjusted value for adjustment type RESTATEMENT. """ conversion_adjustment_type_enum : ConversionAdjustmentTypeEnum = ( client . enums . ConversionAdjustmentTypeEnum ) # Determine the adjustment type. conversion_adjustment_type : int = conversion_adjustment_type_enum [ adjustment_type ] . value # Applies the conversion adjustment to the existing conversion. conversion_adjustment : ConversionAdjustment = client . get_type ( "ConversionAdjustment" ) conversion_action_service : ConversionActionServiceClient = ( client . get_service ( "ConversionActionService" ) ) conversion_adjustment . conversion_action = ( conversion_action_service . conversion_action_path ( customer_id , conversion_action_id ) ) conversion_adjustment . adjustment_type = conversion_adjustment_type conversion_adjustment . adjustment_date_time = adjustment_date_time # Sets the order_id to identify the conversion to adjust. conversion_adjustment . order_id = order_id # As an alternative to setting order_id, you can provide a # gclid_date_time_pair, but setting order_id instead is strongly recommended. # conversion_adjustment.gclid_date_time_pair.gclid = gclid # conversion_adjustment.gclid_date_time_pair.conversion_date_time = ( # conversion_date_time # ) # Sets adjusted value for adjustment type RESTATEMENT. if ( restatement_value and conversion_adjustment_type == conversion_adjustment_type_enum . RESTATEMENT . value ): conversion_adjustment . restatement_value . adjusted_value = float ( restatement_value ) # Uploads the click conversion. Partial failure should always be set to # true. service : ConversionAdjustmentUploadServiceClient = client . get_service ( "ConversionAdjustmentUploadService" ) request : UploadConversionAdjustmentsRequest = client . get_type ( "UploadConversionAdjustmentsRequest" ) request . customer_id = customer_id request . conversion_adjustments . append ( conversion_adjustment ) # Enables partial failure (must be true) request . partial_failure = True response : UploadConversionAdjustmentsResponse = ( service . upload_conversion_adjustments ( request = request ) ) # Extracts the partial failure error if present on the response. error_details = None if response . partial_failure_error : error_details : Iterable [ Any ] = response . partial_failure_error . details i : int conversion_adjustment_result : ConversionAdjustmentResult for i , conversion_adjustment_result in enumerate ( response . results ): # If there's a GoogleAdsFailure in error_details at this position then # the uploaded operation failed and we print the error message. if error_details and error_details [ i ]: error_detail : Any = error_details [ i ] failure_message : GoogleAdsFailure = client . get_type ( "GoogleAdsFailure" ) # Parse the string into a GoogleAdsFailure message instance. # To access class-only methods on the message we retrieve its type. google_ads_failure_class : GoogleAdsFailure = type ( failure_message ) failure_object : GoogleAdsFailure = ( google_ads_failure_class . deserialize ( error_detail . value ) ) error : GoogleAdsError for error in failure_object . errors : # Construct and print a string that details which element in # the operation list failed (by index number) as well as the # error message and error code. print ( "A partial failure at index " f " { error . location . field_path_elements [ 0 ] . index } occurred " f " \n Error message: { error . message } \n Error code: " f " { error . error_code } " ) else : print ( "Uploaded conversion adjustment for conversion action " f "' { conversion_adjustment_result . conversion_action } ' and order " f "ID ' { conversion_adjustment_result . order_id } '." ) if __name__ == "__main__" : # 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 = "v21" ) parser : argparse . ArgumentParser = argparse . ArgumentParser ( description = "Uploads a conversion adjustment." ) # 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" , "--conversion_action_id" , type = str , required = True , help = "The ID of the conversion action to upload the adjustment to." , ) parser . add_argument ( "-d" , "--adjustment_type" , type = str , required = True , choices = [ e . name for e in googleads_client . enums . ConversionAdjustmentTypeEnum if e . name not in ( "UNSPECIFIED" , "UNKNOWN" ) ], help = "The adjustment type, e.g. " "RETRACTION, RESTATEMENT" , ) parser . add_argument ( "-o" , "--order_id" , type = str , required = True , help = ( "The transaction ID of the conversion to adjust. Required if the " "conversion being adjusted meets the criteria described at: " "https://developers.google.com/google-ads/api/docs/conversions/upload-adjustments#requirements." ), ) parser . add_argument ( "-v" , "--adjustment_date_time" , type = str , required = True , help = ( "The date and time of the adjustment. The format is " "'yyyy-mm-dd hh:mm:ss+|-hh:mm', e.g. '2019-01-01 12:32:45-08:00'" ), ) # Optional: Specify an adjusted value for adjustment type RESTATEMENT. # This value will be ignored if you specify RETRACTION as adjustment type. parser . add_argument ( "-r" , "--restatement_value" , type = str , required = False , help = "The adjusted value for adjustment type RESTATEMENT." , ) args : argparse . Namespace = parser . parse_args () try : main ( googleads_client , args . customer_id , args . conversion_action_id , args . adjustment_type , args . order_id , args . adjustment_date_time , args . restatement_value , ) 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 # # Copyright 2020 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 imports conversion adjustments for conversions that already exist. # To set up a conversion action, run add_conversion_action.rb. require 'optparse' require 'google/ads/google_ads' def upload_conversion_adjustment ( customer_id , conversion_action_id , order_id , adjustment_type , adjustment_date_time , restatement_value ) # GoogleAdsClient will read a config file from # ENV['HOME']/google_ads_config.rb when called without parameters client = Google :: Ads :: GoogleAds :: GoogleAdsClient . new # Applies the conversion adjustment to the existing conversion. conversion_adjustment = client . resource . conversion_adjustment do | ca | ca . conversion_action = client . path . conversion_action ( customer_id , conversion_action_id ) ca . adjustment_type = adjustment_type ca . order_id = order_id ca . adjustment_date_time = adjustment_date_time # Set adjusted value for adjustment type RESTATEMENT. if adjustment_type == :RESTATEMENT ca . restatement_value = client . resource . restatement_value do | ra | ra . adjusted_value = restatement_value . to_f end end end # Issue a request to upload the conversion adjustment(s). response = client . service . conversion_adjustment_upload . upload_conversion_adjustments ( customer_id : customer_id , # This example shows just one adjustment but you may upload multiple ones. conversion_adjustments : [ conversion_adjustment ] , partial_failure : true ) if response . partial_failure_error . nil? # Process and print all results for multiple adjustments response . results . each do | result | puts "Uploaded conversion adjustment for conversion action #{ result . conversion_action } " \ "and order ID #{ result . order_id } ." end else # Print any partial errors returned. failures = client . decode_partial_failure_error ( response . partial_failure_error ) puts 'Request failed. Failure details:' failures . each do | failure | failure . errors . each do | error | index = error . location . field_path_elements . first . index puts " \t operation[ #{ index } ] #{ error . error_code . error_code } : #{ error . message } " end end end end if __FILE__ == $0 options = {} # Running the example with -h will print the command line usage. OptionParser . new do | opts | opts . banner = format ( '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 ( '-c' , '--conversion-action-id CONVERSION-ACTION-ID' , String , 'Conversion Action ID' ) do | v | options [ :conversion_action_id ] = v end opts . on ( '-O' , '--order-id ORDER-ID' , String , 'The transaction ID of the conversion to adjust. Required if the conversion being ' \ 'adjusted meets the criteria described at ' \ 'https://developers.google.com/google-ads/api/docs/conversions/upload-adjustments#requirements.' ) do | v | options [ :order_id ] = v end opts . on ( '-a' , '--adjustment-type ADJUSTMENT-TYPE' , String , 'RETRACTION negates a conversion, and RESTATEMENT changes the value of a conversion.' ) do | v | options [ :adjustment_type ] = v end opts . on ( '-A' , '--adjustment-date-time ADJUSTMENT-DATE-TIME' , String , 'The date and time of the adjustment. ' \ 'The format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", ' \ 'e.g. "2019-01-01 12:32:45-08:00".' ) do | v | options [ :adjustment_date_time ] = v end opts . on ( '-r' , '--restatement-value RESTATEMENT-VALUE' , String , '[optional] The adjusted value for adjustment type RESTATEMENT.' ) do | v | options [ :restatement_value ] = v end opts . separator '' opts . separator 'Help:' opts . on_tail ( '-h' , '--help' , 'Show this message' ) do puts opts exit end end . parse! begin upload_conversion_adjustment ( options . fetch ( :customer_id ) . tr ( '-' , '' ), options . fetch ( :conversion_action_id ), options . fetch ( :order_id ), options . fetch ( :adjustment_type ) . to_sym , options . fetch ( :adjustment_date_time ), options [ :restatement_value ] ) rescue Google :: Ads :: GoogleAds :: Errors :: GoogleAdsError = > e e . failure . errors . each do | error | STDERR . printf ( "Error with message: %s \n " , error . message ) error . location & . field_path_elements & . each do | field_path_element | STDERR . printf ( " \t On field: %s \n " , field_path_element . field_name ) 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 2020, 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 imports conversion adjustments for conversions that already exist. # To set up a conversion action, run add_conversion_action.pl. 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::V21::Enums::ConversionAdjustmentTypeEnum qw(RESTATEMENT) ; use Google::Ads::GoogleAds::V21::Services::ConversionAdjustmentUploadService::ConversionAdjustment ; use Google::Ads::GoogleAds::V21::Services::ConversionAdjustmentUploadService::GclidDateTimePair ; use Google::Ads::GoogleAds::V21::Services::ConversionAdjustmentUploadService::RestatementValue ; use Google::Ads::GoogleAds::V21::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 $conversion_action_id = "INSERT_CONVERSION_ACTION_ID_HERE" ; # The transaction ID of the conversion to adjust. Required if the conversion # being adjusted meets the criteria described at # https://developers.google.com/google-ads/api/docs/conversions/upload-adjustments#requirements. my $order_id = "INSERT_ORDER_ID_HERE" ; # RETRACTION negates a conversion, and RESTATEMENT changes the value of a conversion. my $adjustment_type = "INSERT_ADJUSTMENT_TYPE_HERE" ; my $adjustment_date_time = "INSERT_ADJUSTMENT_DATE_TIME_HERE" ; # Optional: Specify an adjusted value below for adjustment type RESTATEMENT. # This value will be ignored if you specify RETRACTION as adjustment type. my $restatement_value = undef ; sub upload_conversion_adjustment { my ( $api_client , $customer_id , $conversion_action_id , $order_id , $adjustment_type , $adjustment_date_time , $restatement_value ) = @_ ; # Applies the conversion adjustment to the existing conversion. my $conversion_adjustment = Google::Ads::GoogleAds::V21::Services::ConversionAdjustmentUploadService:: ConversionAdjustment - > new ({ conversionAction = > Google::Ads::GoogleAds::V21::Utils::ResourceNames:: conversion_action ( $customer_id , $conversion_action_id ), adjustmentType = > $adjustment_type , # Sets the orderId to identify the conversion to adjust. orderId = > $order_id , # As an alternative to setting orderId, you can provide a 'gclid_date_time_pair', # but setting 'order_id' instead is strongly recommended. # gclidDateTimePair = > # Google::Ads::GoogleAds::V21::Services::ConversionAdjustmentUploadService::GclidDateTimePair # ->new({ # gclid => $gclid, # conversionDateTime => $conversion_date_time # } # ), adjustmentDateTime = > $adjustment_date_time , }); # Set adjusted value for adjustment type RESTATEMENT. $conversion_adjustment - > { restatementValue } = Google::Ads::GoogleAds::V21::Services::ConversionAdjustmentUploadService:: RestatementValue - > new ({ adjustedValue = > $restatement_value }) if defined $restatement_value && $adjustment_type eq RESTATEMENT ; # Issue a request to upload the conversion adjustment. my $upload_conversion_adjustments_response = $api_client - > ConversionAdjustmentUploadService () - > upload_conversion_adjustments ({ customerId = > $customer_id , conversionAdjustments = > [ $conversion_adjustment ], partialFailure = > "true" }); # Print any partial errors returned. if ( $upload_conversion_adjustments_response - > { partialFailureError }) { printf "Partial error encountered: '%s'.\n" , $upload_conversion_adjustments_response - > { partialFailureError }{ message }; } # Print the result if valid. my $uploaded_conversion_adjustment = $upload_conversion_adjustments_response - > { results }[ 0 ]; if ( %$uploaded_conversion_adjustment ) { printf "Uploaded conversion adjustment of the conversion action " . "with resource name '%s' for order ID '%s'.\n" , $uploaded_conversion_adjustment - > { conversionAction }, $uploaded_conversion_adjustment - > { orderId }; } 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 , "conversion_action_id=i" = > \ $conversion_action_id , "order_id=s" = > \ $order_id , "adjustment_type=s" = > \ $adjustment_type , "adjustment_date_time=s" = > \ $adjustment_date_time , "restatement_value=f" = > \ $restatement_value ); # 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 , $conversion_action_id , $order_id , $adjustment_type , $adjustment_date_time ); # Call the example. upload_conversion_adjustment ( $api_client , $customer_id =~ s/-//g r , $conversion_action_id , $order_id , $adjustment_type , $adjustment_date_time , $restatement_value ); =pod =head1 NAME upload_conversion_adjustment =head1 DESCRIPTION This example imports conversion adjustments for conversions that already exist. To set up a conversion action, run add_conversion_action.pl. =head1 SYNOPSIS upload_conversion_adjustment.pl [options] -help Show the help message. -customer_id The Google Ads customer ID. -conversion_action_id The ID of the conversion action to upload to. -order_id The order ID of the conversion. Strongly recommended instead of using GCLID and conversion date time. -adjustment_type The type of adjustment, e.g. RETRACTION, RESTATEMENT. -adjustment_date_time The date and time of the adjustment. The format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", e.g. "2019-01-01 12:32:45-08:00". -restatement_value [optional] The adjusted value for adjustment type RESTATEMENT. =cut
