تعديل الإحالات الناجحة الحالية

استدعِ طريقة Conversion.update() لإجراء الأنواع التالية من التغييرات على إحالة ناجحة حالية واحدة أو أكثر:

• عدِّل الأرباح أو رمز العملة أو الكمية.
• عدِّل معرّف الطلب الذي يقدّمه المعلِن وأي متغيّرات Floodlight المخصّصة.
• أزِل الإحالة الناجحة عن طريق تغيير conversion.state من ACTIVE إلى REMOVED.

لا تتيح "إعلانات شبكة البحث 360" تغيير ما يلي:

• تاريخ الإحالة الناجحة.
• نوع الإحالة الناجحة
• الكلمة الرئيسية أو الإعلان أو الزيارة المنسوبة إلى الإحالة الناجحة
• اسم نشاط Floodlight أو نشاطه

في المقابل، يمكنك دائمًا وضع علامة "تمّت الإزالة" على إحالة ناجحة حالية وتحميل إحالة ناجحة جديدة بالتاريخ أو النوع أو أرقام تعريف تحديد المصدر أو نشاط Floodlight المعدّل (احرص أيضًا على تحديد conversionId جديد).

كما هي الحال في Conversion.insert()، إذا كان طلب التعديل يحدّد عدة إحالات ناجحة، ستحاول "إعلانات شبكة البحث 360" تعديل كل إحالة ناجحة وفقًا لأفضل جهد ممكن بدلاً من تعديل المجموعة بأكملها على أنّها معاملة شاملة أو لا. وإذا تعذّر إجراء بعض التعديلات في دفعة معيّنة، قد تنجح بعض التحديثات الأخرى. ننصحك بقراءة الردّ لكل إحالة ناجحة يتم تعديلها للتأكّد من نجاح عملية التعديل.

إرسال طلب تعديل

يتم استخدام معظم الحقول التي تحدّدها في Conversion.update() لتحديد الإحالات الناجحة التي تريد تعديلها. يمكنك استخدام أيّ من الطريقتَين التاليتَين لتحديد إحالة ناجحة حالية:

• حدِّد clickId للإحالة الناجحة.
  • يجب أن تكون جميع الإحالات الناجحة المعدَّلة خلال 60 يومًا من وقت إنشاء معرّف النقرة.
• تحديد criterionId للإحالة الناجحة (رقم تعريف الكلمة الرئيسية)

تتطلّب كلتا الطريقتين تحديد conversionId وconversionTimestamp والمعاملة type الخاصة بالإحالة الناجحة.

بالإضافة إلى ذلك، إذا كانت الإحالة الناجحة الأصلية تحدّد revenueMicros أو currencyCode أو quantityMillis، يجب أن يحدّد طلب التعديل هذه البيانات حتى إذا لم تكن تغيّرها.

تحديد الإحالة الناجحة حسب معرّف النقرة

إذا حدّدت الإحالة الناجحة في الأصل معرّف نقرة، يمكنك إرسال طلب Conversion.update() يحدّد الحقول التالية:

• clickId
• conversionId
• conversionTimestamp
• type
• state (مطلوبة فقط إذا أردت تغيير الحالة إلى "تمت الإزالة" أو "نشطة")
• quantityMillis (فقط في حال تحديدها في الإحالة الناجحة الأصلية)
• revenueMicros (فقط في حال تحديدها في الإحالة الناجحة الأصلية)
• currencyCode (فقط في حال تحديدها في الإحالة الناجحة الأصلية)

مثال

في ما يلي مثال على إحالتَين ناجحتَين حاليتَين:

{
 "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"
  }
 ]
}        

استخدِم النص البرمجي لأداة "إعلانات شبكة البحث 360" لإرسال هذا الطلب.

لإرسال طلب JSON POST أولي، يمكنك استخدام النص البرمجي sa360Api.py على النحو التالي:

1. انسخ نموذج كائن JSON (كل ما بين القوسَين المعقوفَين وبما فيهما) في ملف نصي جديد باسم request.txt.
2. غيِّر رقم تعريف الوكالة الوارد في رمز JSON إلى رقم تعريف وكالتك.
3. أزِل أي تعليقات، مثل // The date column segments the report by individual days..
4. جمِّع بيانات اعتماد OAuth 2.0 في سلسلة واحدة مفصولة بفواصل على النحو التالي:
   client-ID,client-secret,refresh-token
   (هذه هي السلسلة نفسها التي يصدرها sa360Api.py عند تشغيل sa360Api.py --login كما هو موضّح في إعداد التفويض.)
5. استدعِ sa360Api.py على النحو التالي:
   sa360Api.py --cred CREDENTIALS --server API-method --put < request.txt
   في الأمر أعلاه، استبدِل CREDENTIALS بالسلسلة التي جمعتها في الخطوة السابقة.
   استبدِل اسم طريقة PUT في المربّع أدناه باسم API-method.

   مثال:
   sa360Api.py --cred 123456789123.apps.googleusercontent.com,ABCDEFGHIJKLMNOPQR_abcdef,1/HIJklM01OPQR23NOP456rst890uvw --server https://www.googleapis.com/doubleclicksearch/v2/conversion --put < request.txt

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())

تحديد الإحالة الناجحة حسب رقم تعريف الكلمة الرئيسية

إذا لم يكن لديك إذن الوصول إلى رقم تعريف النقرة، أو إذا كانت الإحالة الناجحة منسوبة في الأصل إلى كلمة رئيسية أو كلمة رئيسية/إعلان، يمكنك إرسال طلب Conversion.update() يحدّد الحقول التالية:

• criterionId (رقم تعريف الكلمة الرئيسية)
• conversionId
• conversionTimestamp
• type
• state (مطلوبة فقط إذا أردت تغيير الحالة إلى "تمت الإزالة" أو "نشطة")
• quantityMillis (فقط في حال تحديدها في الإحالة الناجحة الأصلية)
• revenueMicros (فقط في حال تحديدها في الإحالة الناجحة الأصلية)
• currencyCode (فقط في حال تحديدها في الإحالة الناجحة الأصلية)

يمكنك اختياريًا تحديد أرقام تعريف أخرى، مثل رقم تعريف الإعلان المتعلّق بالإحالة الناجحة ورقم تعريف الحملة وما إلى ذلك، ولكنك لست بحاجة إلى ذلك. تحتاج "إعلانات شبكة البحث 360" فقط إلى أرقام التعريف الواردة في القائمة أعلاه لتحديد إحالة ناجحة حالية.

مثال

في ما يلي مثال على إحالة ناجحة حالية:

{
 "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.

استخدِم النص البرمجي لأداة "إعلانات شبكة البحث 360" لإرسال هذا الطلب.

لإرسال طلب JSON POST أولي، يمكنك استخدام النص البرمجي sa360Api.py على النحو التالي:

1. انسخ نموذج كائن JSON (كل ما بين القوسَين المعقوفَين وبما فيهما) في ملف نصي جديد باسم request.txt.
2. غيِّر رقم تعريف الوكالة الوارد في رمز JSON إلى رقم تعريف وكالتك.
3. أزِل أي تعليقات، مثل // The date column segments the report by individual days..
4. جمِّع بيانات اعتماد OAuth 2.0 في سلسلة واحدة مفصولة بفواصل على النحو التالي:
   client-ID,client-secret,refresh-token
   (هذه هي السلسلة نفسها التي يصدرها sa360Api.py عند تشغيل sa360Api.py --login كما هو موضّح في إعداد التفويض.)
5. استدعِ sa360Api.py على النحو التالي:
   sa360Api.py --cred CREDENTIALS --server API-method --put < request.txt
   في الأمر أعلاه، استبدِل CREDENTIALS بالسلسلة التي جمعتها في الخطوة السابقة.
   استبدِل اسم طريقة PUT في المربّع أدناه باسم API-method.

   مثال:
   sa360Api.py --cred 123456789123.apps.googleusercontent.com,ABCDEFGHIJKLMNOPQR_abcdef,1/HIJklM01OPQR23NOP456rst890uvw --server https://www.googleapis.com/doubleclicksearch/v2/conversion --put < request.txt

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" لكل إحالة ناجحة تم تعديلها، مثل رقم تعريف الحملة ورقم تعريف المجموعة الإعلانية ورقم تعريف الكلمة الرئيسية (المعيار).

في حال تعذَّر التحقّق من صحة تعديل واحد أو أكثر أو تحميله، سيتضمن الرد رسائل تعذُّر لكل تعديل تعذّر تحميله. ولا يحتوي الردّ على رسائل بشأن الإحالات الناجحة التي تم تعديلها بنجاح. لمزيد من المعلومات عن رسائل الخطأ هذه، راجِع التعامل مع ردود "إعلانات شبكة البحث 360" لطلبات الإدراج.