Conversion.update()
メソッドを呼び出して、1 つ以上の既存のコンバージョンに対して次の変更を行います。
- 収益、通貨コード、数量を変更します。
- 広告主から提供されたオーダー ID と、カスタム Floodlight 変数を変更します。
conversion.state
をACTIVE
からREMOVED
に変更して、コンバージョンを削除します。
検索広告 360 では、次の項目の編集はサポートされていません。
- コンバージョンの日付。
- コンバージョン タイプ
- コンバージョンに関連付けられたキーワードまたは訪問。
- Floodlight アクティビティやアクティビティ名
なお、既存のコンバージョンを [削除済み] としてマークしてから、日付、タイプ、アトリビューション ID、Floodlight アクティビティを更新して新しいコンバージョンをアップロードする操作はいつでも行えます(新しい conversionId
も指定してください)。
Conversion.insert()
と同様に、更新リクエストで複数のコンバージョンを指定した場合は、バッチ全体をオール オア ナッシング トランザクションとして更新するのではなく、ベスト エフォートを基本として各コンバージョンの更新を試みます。バッチ内の一部の更新が失敗しても、他の更新は成功する場合があります。更新されたコンバージョンごとにレスポンスを読み取り、更新が正常に完了したことを確認することをおすすめします。
(2025 年更新)dsConversionId
の非推奨
現在、dsConversionId
または conversionId
を使用してコンバージョンを特定して編集できます。dsConversionId
フィールドは 2025 年第 3 四半期に非推奨になります。今後は、conversionId
を使用して Search Ads 360 Conversion API でコンバージョンを編集する必要があります。
主な変更点:
-
dsConversionId
のサポート終了:dsConversionID
は、Search Ads 360 Reporting API(conversion.id
という名称)またはレポート管理画面(「コンバージョン ID」という名称)でサポートされなくなります。 -
conversionId
の要件:conversionId
は、Search Ads 360 Conversion API でコンバージョンを編集する際に必須のフィールドになります。
conversionId
の取得方法:
-
Search Ads 360 Reporting API: Search Ads 360 Reporting API を使用して
advertiser_conversion_id
を取得できます。この値は、編集に必要なconversionId
に対応します。 -
検索広告 360 の管理画面: 検索広告 360 の管理画面のコンバージョン レポート ページで「広告主のコンバージョン ID」を確認できます。
更新リクエストを送信する
Conversion.update()
で指定するフィールドのほとんどは、更新するコンバージョンの識別に使用されます。既存のコンバージョンを特定するには、次のいずれかの方法を使用します。
- コンバージョンの
clickId
を指定する- 編集するコンバージョンはすべて、クリック ID が生成された日から 60 日以内のものである必要があります。
- コンバージョンの
criterionId
(キーワード ID)を指定します。
どちらの方法でも、コンバージョンの conversionId
、conversionTimestamp
、トランザクション type
を指定する必要があります。
また、元のコンバージョンで revenueMicros
と currencyCode
または quantityMillis
が指定されている場合は、変更しない場合でも、更新リクエストでこのデータを指定する必要があります。
クリック ID でコンバージョンを特定する
コンバージョンでクリック ID が最初に指定されている場合は、次のフィールドを指定して Conversion.update()
リクエストを送信できます。
clickId
conversionId
conversionTimestamp
type
state
(ステータスを削除済みまたは有効に変更する場合にのみ必要)quantityMillis
(元のコンバージョンで指定されている場合のみ)revenueMicros
(元のコンバージョンで指定されている場合のみ)currencyCode
(元のコンバージョンで指定されている場合のみ)
例
既存のコンバージョンの例を 2 つ示します。
{ "kind": "doubleclicksearch#conversionList", "conversion" : [{ "clickId" : "COiYmPDTv7kCFcP0KgodOzQAAA", "conversionId" : "test_20130906_10", "conversionTimestamp" : "1378710000000", "segmentationType" : "FLOODLIGHT", "segmentationName" : "Test", "type": "TRANSACTION", "revenueMicros": "100000000", // 100 million revenueMicros is equivalent to $100 of revenue "currencyCode": "USD" }, { "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA", "conversionId": "test_1383337059137", "conversionTimestamp": "1378710000000", "segmentationType" : "FLOODLIGHT", "segmentationName" : "Test", "type": "ACTION", "quantityMillis": "1000" }] }
次のリクエストは、前の例のいずれかのコンバージョンを更新し、もう一方を削除します。
JSON
Conversion.update()
リクエストでは PUT HTTP メソッドが使用されます。
PUT https://www.googleapis.com/doubleclicksearch/v2/conversion Authorization: Bearer your OAuth 2.0 access token Content-type: application/json { "kind": "doubleclicksearch#conversionList", "conversion": [ { "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with data from your site "conversionId": "test_20130906_10", "conversionTimestamp": "1378710000000", "type": "TRANSACTION", "revenueMicros": "90000000", // 90 million revenueMicros is equivalent to $90 of revenue "currencyCode": "USD" }, { "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with data from your site "conversionId": "test_1383337059137", "conversionTimestamp": "1378710000000", "type": "ACTION", "quantityMillis": "1000", "state": "REMOVED" } ] }
Java
/** * Instantiate the Doubleclicksearch service, create a conversion that updates an existing conversion, * and upload the conversions. */ public static void main(String[] args) throws Exception { Doubleclicksearch service = getService(); // See Set Up Your Application. // Set up a List to keep track of each conversion you create. List<Conversion> conversions = new Vector<Conversion>(); // Create a conversion and add it to the conversion list. // Just to get a little fancy, the updateConversionFromVisit() method can be used for all // visit conversions, including conversions that don't specify quantity, revenue, or currency. // If quantityMillis wasn't specified in the original conversion, specify -1L for the // quantityMillis parameter. Likewise, if revenueMicros wasn't specified originally, // specify -1L for the revenueMicros parameter and an empty string for currency. conversionList = updateConversionFromVisit( conversionList, "COiYmPDTv7kCFcP0KgodOzQAAA", // clickId. Replace with data from your site "test_20130906_10", // conversionId 1378710000000L, // timeStamp "TRANSACTION", // type "", // state -1L, // quantityMillis 90000000L, // revenueMicros. Equivalent to $90 of revenue "USD"); // currencyCode // Here's a conversion that needs to be removed. Just set the state parameter to "REMOVED". conversionList = updateConversionFromVisit( conversionList, "COiYmPDTv7kCFcP0KgodOzQAAA", // clickId. Replace with data from your site "test_1383337059137", // conversionId 1378710000000L, // timeStamp "ACTION", // type "REMOVED", // state 1000L, // quantityMillis -1L, // revenueMicros ""); // currencyCode // Upload the List and handle the response. uploadConversions(conversions, service); // See an example in Add New Conversions. } /** * Create a conversion and add it to a List<Conversion>. */ private static List<Conversion> updateConversionFromVisit(List<Conversion> conversions, String clickId, String conversionId, Long timeStamp, String type, String state, Long quantity, Long revenue, String currency) { // Identifies the existing conversion. Conversion conversion = new Conversion() .setClickId(clickId) .setConversionId(conversionId) .setConversionTimestamp(BigInteger.valueOf(timeStamp)) .setType(type); // Only add these fields if the value is not empty greater than -1. if(!state.isEmpty()) conversion.setState(state); if (quantity > -1L) { conversion.setQuantityMillis(quantity); } if (revenue > -1L) { conversion.setRevenueMicros(revenue); if (!currency.isEmpty()) { conversion.setCurrencyCode(currency); } else { System.err.println(String.format( "Can't add conversion %s. It specifies revenue but no currency.", conversion.getConversionId())); return conversions; } } conversions.add(conversion); return conversions; }
Python
def update_conversion(service): """Change the revenue for one existing conversion and remove another. Args: service: An authorized Doubleclicksearch service. See Set Up Your Application. """ request = service.conversion().update( body= { 'conversion' : [{ 'clickId' : 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with data from your site 'conversionId' : 'test_20130906_13', 'conversionTimestamp' : '1378710000000', 'segmentationType' : 'FLOODLIGHT', 'segmentationName' : 'Test', 'type': 'TRANSACTION', 'revenueMicros': '90000000', // 90 million revenueMicros is equivalent to $90 of revenue 'currencyCode': 'USD' }, { 'clickId': 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with data from your site 'conversionId': 'test_1383337059137_01', 'conversionTimestamp': '1378710000000', 'segmentationType' : 'FLOODLIGHT', 'segmentationName' : 'Test', 'type': 'ACTION', 'quantityMillis': '1000', 'state': 'REMOVED' }] } ) pprint.pprint(request.execute())
キーワード ID でコンバージョンを特定する
クリック ID にアクセスできない場合や、コンバージョンが元々キーワードまたはキーワードと広告に関連付けられている場合は、次のフィールドを指定して Conversion.update()
リクエストを送信できます。
criterionId
(キーワード ID)conversionId
conversionTimestamp
type
state
(ステータスを削除済みまたは有効に変更する場合にのみ必要)quantityMillis
(元のコンバージョンで指定されている場合のみ)revenueMicros
(元のコンバージョンで指定されている場合のみ)currencyCode
(元のコンバージョンで指定されている場合のみ)
必要に応じて、コンバージョンの広告 ID、キャンペーン ID などの他の ID を指定することもできますが、必須ではありません。検索広告 360 で既存のコンバージョンを識別するために必要な ID は、上記のリストに記載されている ID のみです。
例
既存のコンバージョンの例を次に示します。
{ "kind": "doubleclicksearch#conversionList", "conversion" : [{ "agencyId": "12300000000000456", "advertiserId": "45600000000010291", "engineAccountId": "700000000042441", "campaignId": "71700000002044839", "adGroupId": "58700000032026064", "criterionId": "43700004289911004", "adId": "44700000155906860", "conversionId": "test_1383157519886", "conversionTimestamp": "1378710000000", "type": "ACTION", "quantityMillis": "1000", "segmentationType": "FLOODLIGHT", "segmentationName": "Test" }] }
次のリクエストは、コンバージョンのタイムスタンプを更新します。
JSON
Conversion.update()
リクエストでは PUT HTTP メソッドが使用されます。
PUT https://www.googleapis.com/doubleclicksearch/v2/conversion Authorization: Bearer your OAuth 2.0 access token Content-type: application/json { "kind": "doubleclicksearch#conversionList", "conversion": [ { "criterionId": "43700004289911004", // Replace with your ID "conversionId": "test_1383157519886", "conversionTimestamp": "1378710000000", "type": "ACTION", "quantityMillis": "3000" } ] }
Java
// Send conversion data to updateConversion, which creates a conversion and adds it // to the conversion list. conversionList = updateConversionFromKeyword(conversionList, 43700004289911004L, // criterionId. Replace with your ID "test_1383157519886", // conversionId 1378710000000L, // timeStamp "ACTION", // type "", // state 3000L, // quantityMillis -1L, // revenueMicros ""); // currencyCode private static List<Conversion> updateConversionFromKeyword(List<Conversion> conversions, Long criterionId, String conversionId, Long timeStamp, String type, String state, Long quantity, Long revenue, String currency ) { Conversion conversion = new Conversion() .setCriterionId(criterionId) .setConversionId(conversionId) .setConversionTimestamp(BigInteger.valueOf(timeStamp)) .setType(type); // Only add these fields if the value is not empty greater than -1. if(!state.isEmpty()) conversion.setState(state); if (quantity > -1L) { conversion.setQuantityMillis(quantity); } if (revenue > -1L) { conversion.setRevenueMicros(revenue); if (!currency.isEmpty()) { conversion.setCurrencyCode(currency); } else { System.err.println(String.format( "Can't add conversion %s. It specifies revenue but no currency.", conversion.getConversionId())); return conversions; } } conversions.add(conversion); return conversions; }
Python
def update_conversion(service): """Change the timestamp of a conversion. Use only the keyword id (criterionId) to identify the conversion. Args: service: An authorized Doubleclicksearch service. See Set Up Your Application. """ request = service.conversion().update( body= { 'conversion': [{ 'criterionId': '43700004289911004', // Replace with your ID 'conversionId': 'test_1383157519886', 'conversionTimestamp': '1378760000000', 'type': 'ACTION', 'quantityMillis': '1000' }] } ) pprint.pprint(request.execute())
検索広告 360 のレスポンスに対応する
更新リクエストのレスポンスは、挿入リクエストのレスポンスと同じです。検索広告 360 では、リクエスト内のすべてのコンバージョンが正常に更新された場合にのみ、成功が示されます。
リクエストが成功すると、更新された各コンバージョンの検索広告 360 内部表現(キャンペーン ID、広告グループ ID、キーワード(条件)ID など)がレスポンスに含まれます。
1 つ以上の更新の検証またはアップロードが失敗した場合、レスポンスには、失敗した更新ごとに失敗メッセージが含まれます。レスポンスには、正常に更新されたコンバージョンに関するメッセージは含まれません。これらのエラー メッセージの詳細については、挿入リクエストのSearch Ads 360 のレスポンスの処理をご覧ください。