تنبيه: يتم عرض مستندات واجهة REST API. تستخدم معظم مكتبات العملاء الرسمية خدمة gRPC. يمكنك الاطلاع على مقدمة عن REST للحصول على التفاصيل.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

Method: customers.uploadClickConversions

طلب HTTP
مَعلمات المسار
نص الطلب
- تمثيل JSON
نص الاستجابة
- تمثيل JSON
نطاقات التفويض
ClickConversion
- تمثيل JSON
ExternalAttributionData
- تمثيل JSON
CartData
- تمثيل JSON
السلعة
- تمثيل JSON
ConversionEnvironment
ClickConversionResult
- تمثيل JSON
جرِّبه الآن

تعالج الإحالات الناجحة الناتجة عن النقرات المحدّدة.

قائمة الأخطاء الملموسة: AuthenticationError AuthorizationError ConversionUploadError HeaderError InternalError PartialFailureError QuotaError RequestError

طلب HTTP

POST https://googleads.googleapis.com/v16/customers/{customerId}:uploadClickConversions

يستخدم عنوان URL بنية تحويل الترميز gRPC.

معلمات المسار

المَعلمات

المَعلمات
`customerId`	`string` مطلوبة. رقم تعريف العميل الذي يُجري عملية التحميل

customerId

string

مطلوبة. رقم تعريف العميل الذي يُجري عملية التحميل

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON
{ "conversions": [ { object (`ClickConversion`) } ], "partialFailure": boolean, "validateOnly": boolean, "debugEnabled": boolean, "jobId": integer }

الحقول
`conversions[]`	`object (ClickConversion)` مطلوبة. الإحالات الناجحة التي يتم تحميلها.
`partialFailure`	`boolean` مطلوبة. في حال الصواب، سيتم تنفيذ عمليات ناجحة وعرض العمليات غير الصالحة أخطاء. وفي حال كانت القيمة خاطئة، سيتم تنفيذ جميع العمليات في معاملة واحدة فقط إذا كانت جميعها صالحة. يجب ضبط هذه السياسة دائمًا على "صحيح". يمكنك الانتقال إلى https://developers.google.com/google-ads/api/docs/best-practices/partial-failures للحصول على مزيد من المعلومات حول الفشل الجزئي.
`validateOnly`	`boolean` إذا كانت الإجابة "صحيح"، يتم التحقّق من صحة الطلب ولكن لا يتم تنفيذه. يتم عرض الأخطاء فقط وليس النتائج.
`debugEnabled`	`boolean` في حال اختيار القيمة الصحيحة، ستُجري واجهة برمجة التطبيقات جميع عمليات التحقّق من التحميل وتعرض الأخطاء في حال العثور على أي أخطاء. أمّا في حال اختيار القيمة "false"، فسيتم فقط إجراء عمليات التحقق الأساسية من بيانات الإدخال، وتخطّي عمليات التحميل اللاحقة، وإرجاع النتائج حتى في حال عدم العثور على أي نقرة على عنصر `userIdentifiers` المقدَّم. يؤثّر هذا الإعداد فقط في الإحالات الناجحة المحسّنة للعملاء المحتملين الذين يستخدمون `userIdentifiers` بدلاً من `GCLID` أو `GBRAID` أو `WBRAID`. عند تحميل الإحالات الناجحة المحسّنة للعملاء المحتملين، عليك تحميل كل أحداث الإحالات الناجحة إلى واجهة برمجة التطبيقات، بما في ذلك الأحداث التي قد لا تكون واردة من الحملات على "إعلانات Google". سيؤدي تحميل حدث ليس من حملة على "إعلانات Google" إلى ظهور خطأ `CLICK_NOT_FOUND` في حال ضبط هذا الحقل على `true`. بما أنّ هذه الأخطاء متوقعة لهذه الأحداث، اضبط هذا الحقل على `false` حتى تتمكّن من التأكّد من تنسيق عمليات التحميل بشكل سليم مع تجاهل أخطاء `CLICK_NOT_FOUND` من جميع الإحالات الناجحة التي ليست من حملة على "إعلانات Google". سيتيح لك ذلك التركيز فقط على الأخطاء التي يمكنك معالجتها. والقيمة التلقائية هي "خطأ".
`jobId`	`integer` اختياريّ. إدخال اختياري لضبط معرّف الوظيفة يجب أن يكون الرقم غير سالب أقل من 2^31 إذا تم تقديمه. في حال عدم توفير هذا الحقل، ستنشئ واجهة برمجة التطبيقات معرّف الوظيفة في النطاق [2^31, (2^63)-1]. ستعرض واجهة برمجة التطبيقات قيمة هذا الطلب في الحقل `jobId` في `UploadClickConversionsResponse`.

نص الاستجابة

رسالة الرد لـ "ConversionUploadService.UploadClickConversions".

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON
{ "partialFailureError": { object (`Status`) }, "results": [ { object (`ClickConversionResult`) } ], "jobId": string }

الحقول

الحقول
`partialFailureError`	`object (Status)` الأخطاء التي تتعلّق بحالات تعذُّر الإحالات الناجحة في وضع الفشل الجزئي. يتم عرضه عند حدوث جميع الأخطاء داخل الإحالات الناجحة. وفي حال حدوث أي أخطاء خارج الإحالات الناجحة (على سبيل المثال، أخطاء المصادقة)، نعرض خطأ على مستوى استدعاء إجراء عن بُعد (RPC). يمكنك الانتقال إلى https://developers.google.com/google-ads/api/docs/best-practices/partial-failures للحصول على مزيد من المعلومات حول الفشل الجزئي.
`results[]`	`object (ClickConversionResult)` يُرسَل مقابل الإحالات الناجحة التي تمت معالجتها بنجاح. سيكون Proto فارغًا للصفوف التي تلقّت خطأ. لا يتم عرض النتائج عندما تكون trueOnly صحيحة.
`jobId`	`string (int64 format)` معرّف الوظيفة لدفعة التحميل

partialFailureError

object (Status)

الأخطاء التي تتعلّق بحالات تعذُّر الإحالات الناجحة في وضع الفشل الجزئي. يتم عرضه عند حدوث جميع الأخطاء داخل الإحالات الناجحة. وفي حال حدوث أي أخطاء خارج الإحالات الناجحة (على سبيل المثال، أخطاء المصادقة)، نعرض خطأ على مستوى استدعاء إجراء عن بُعد (RPC). يمكنك الانتقال إلى https://developers.google.com/google-ads/api/docs/best-practices/partial-failures للحصول على مزيد من المعلومات حول الفشل الجزئي.

results[]

object (ClickConversionResult)

يُرسَل مقابل الإحالات الناجحة التي تمت معالجتها بنجاح. سيكون Proto فارغًا للصفوف التي تلقّت خطأ. لا يتم عرض النتائج عندما تكون trueOnly صحيحة.

jobId

string (int64 format)

معرّف الوظيفة لدفعة التحميل

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

https://www.googleapis.com/auth/adwords

لمزيد من المعلومات، راجِع نظرة عامة على بروتوكول OAuth 2.0.

ClickConversion

إحالة ناجحة ناتجة عن النقر.

تمثيل JSON

تمثيل JSON
{ "gbraid": string, "wbraid": string, "externalAttributionData": { object (`ExternalAttributionData`) }, "customVariables": [ { object (`CustomVariable`) } ], "cartData": { object (`CartData`) }, "userIdentifiers": [ { object (`UserIdentifier`) } ], "conversionEnvironment": enum (`ConversionEnvironment`), "consent": { object (`Consent`) }, "gclid": string, "conversionAction": string, "conversionDateTime": string, "conversionValue": number, "currencyCode": string, "orderId": string }

{
  "gbraid": string,
  "wbraid": string,
  "externalAttributionData": {
    object (ExternalAttributionData)
  },
  "customVariables": [
    {
      object (CustomVariable)
    }
  ],
  "cartData": {
    object (CartData)
  },
  "userIdentifiers": [
    {
      object (UserIdentifier)
    }
  ],
  "conversionEnvironment": enum (ConversionEnvironment),
  "consent": {
    object (Consent)
  },
  "gclid": string,
  "conversionAction": string,
  "conversionDateTime": string,
  "conversionValue": number,
  "currencyCode": string,
  "orderId": string
}

الحقول
`gbraid`	`string` معرّف النقرة للنقرات المرتبطة بالإحالات الناجحة للتطبيق والناتجة من أجهزة iOS بدءًا من iOS14.
`wbraid`	`string` معرّف النقرة للنقرات المرتبطة بالإحالات الناجحة على الموقع الإلكتروني والناتجة من أجهزة iOS بدءًا من iOS14.
`externalAttributionData`	`object (ExternalAttributionData)` بيانات إضافية عن الإحالات الناجحة التي يكون مصدرها خارجيًا هذا الحقل مطلوب للإحالات الناجحة التي تتضمّن إجراء إحالة ناجحة منسوبًا خارجيًا، ولكن يجب عدم ضبطه بطريقة أخرى.
`customVariables[]`	`object (CustomVariable)` المتغيّرات المخصّصة المرتبطة بهذه الإحالة الناجحة.
`cartData`	`object (CartData)` بيانات سلة التسوّق المرتبطة بهذه الإحالة الناجحة.
`userIdentifiers[]`	`object (UserIdentifier)` معرّفات المستخدمين المرتبطة بهذه الإحالة الناجحة. لا يتم دعم سوى تعديلات البريد الإلكتروني المجزّأة وتجزئة رقم الهاتف المجزّأ لعمليات تحميل الإحالات الناجحة. الحد الأقصى لعدد معرّفات المستخدمين لكل إحالة ناجحة هو 5.
`conversionEnvironment`	`enum (ConversionEnvironment)` البيئة التي تم تسجيل هذه الإحالة الناجحة فيها، مثل التطبيق أو الويب.
`consent`	`object (Consent)` إعداد الموافقة للحدث
`gclid`	`string` معرّف النقرة من Google (gclid) المرتبط بهذه الإحالة الناجحة.
`conversionAction`	`string` اسم المورد لإجراء الإحالة الناجحة المرتبط بهذه الإحالة الناجحة. ملاحظة: على الرغم من أنّ اسم المورد هذا يتألف من رقم تعريف عميل ومعرّف إجراء إحالة ناجحة، ستتجاهل عملية التحقّق الرقم التعريفي للعميل وستستخدم رقم تعريف إجراء الإحالة الناجحة كمعرّف إجراء الإحالة الناجحة الوحيد.
`conversionDateTime`	`string` تاريخ وقت حدوث الإحالة الناجحة. يجب أن يقع بعد وقت النقرة. يجب تحديد المنطقة الزمنية. التنسيق هو "yyyy-mm-dd hh:mm:ss+\|-hh:mm"، على سبيل المثال، "01-01-2019 12:32:45-08:00".
`conversionValue`	`number` قيمة الإحالة الناجحة للمعلِن.
`currencyCode`	`string` العملة المرتبطة بقيمة الإحالة الناجحة. هذا هو رمز العملة المكوّن من 3 أحرف وفقًا لمعيار ISO 4217. على سبيل المثال: SAR أو EUR.
`orderId`	`string` مُعرّف الطلب المرتبط بالإحالة الناجحة. لا يمكن استخدام مُعرّف الطلب إلا لإحالة ناجحة واحدة لكل إجراء إحالة ناجحة.

ExternalAttributionData

يحتوي على معلومات إضافية عن الإحالات الناجحة التي يكون مصدرها خارجيًا.

تمثيل JSON
{ "externalAttributionCredit": number, "externalAttributionModel": string }

الحقول

الحقول
`externalAttributionCredit`	`number` يمثل ذلك الجزء من الإحالة الناجحة المنسوبة إلى النقرة في "إعلانات Google".
`externalAttributionModel`	`string` تُحدِّد اسم نموذج الإحالة.

externalAttributionCredit

number

يمثل ذلك الجزء من الإحالة الناجحة المنسوبة إلى النقرة في "إعلانات Google".

externalAttributionModel

string

تُحدِّد اسم نموذج الإحالة.

CartData

يحتوي على معلومات إضافية حول بيانات سلة التسوّق.

تمثيل JSON
{ "merchantId": string, "feedCountryCode": string, "feedLanguageCode": string, "localTransactionCost": number, "items": [ { object (`Item`) } ] }

الحقول
`merchantId`	`string (int64 format)` معرّف Merchant Center الذي تمّ تحميل السلع إليه.
`feedCountryCode`	`string` رمز البلد المرتبط بالخلاصة التي تمّ تحميل السلع فيها.
`feedLanguageCode`	`string` رمز اللغة المرتبط بالخلاصة التي تمّ تحميل السلع فيها.
`localTransactionCost`	`number` مجموع كل الخصومات على مستوى المُعاملة، مثل الشحن المجاني وخصومات القسائم لسلة التسوّق بالكامل. يكون رمز العملة هو نفسه الرمز الوارد في رسالة Clickconversion.
`items[]`	`object (Item)` بيانات السلع التي تمّ شراؤها

المنتج/الخدمة

تحتوي على بيانات عن السلع التي تم شراؤها.

تمثيل JSON
{ "productId": string, "quantity": integer, "unitPrice": number }

الحقول

الحقول
`productId`	`string` معرّف التسوّق للسلعة. يجب أن تكون القيمة مساوية لمعرّف المنتج في Merchant Center.
`quantity`	`integer` عدد السلع المُباعة.
`unitPrice`	`number` سعر الوحدة غير شامل للضرائب أو تكاليف الشحن أو أيّ خصومات على مستوى المُعاملة. يكون رمز العملة هو نفسه الرمز الوارد في رسالة Clickconversion.

productId

string

معرّف التسوّق للسلعة. يجب أن تكون القيمة مساوية لمعرّف المنتج في Merchant Center.

quantity

integer

عدد السلع المُباعة.

unitPrice

number

سعر الوحدة غير شامل للضرائب أو تكاليف الشحن أو أيّ خصومات على مستوى المُعاملة. يكون رمز العملة هو نفسه الرمز الوارد في رسالة Clickconversion.

ConversionEnvironment

بيئة الإحالة الناجحة للإحالة الناجحة التي تم تحميلها.

عمليات التعداد
`UNSPECIFIED`	عدم تحديد صيغة مخاطبة
`UNKNOWN`	تُستخدَم هذه السمة للقيمة المعروضة فقط. يعرض قيمة غير معروفة في هذا الإصدار.
`APP`	تم تسجيل الإحالة الناجحة في أحد التطبيقات.
`WEB`	تم تسجيل الإحالة الناجحة على موقع إلكتروني.

ClickConversionResult

تحديد معلومات لإحالة ناجحة ClickConversion تمت معالجتها بنجاح.

تمثيل JSON
{ "gbraid": string, "wbraid": string, "userIdentifiers": [ { object (`UserIdentifier`) } ], "gclid": string, "conversionAction": string, "conversionDateTime": string }

الحقول
`gbraid`	`string` معرّف النقرة للنقرات المرتبطة بالإحالات الناجحة للتطبيق والناتجة من أجهزة iOS بدءًا من iOS14.
`wbraid`	`string` معرّف النقرة للنقرات المرتبطة بالإحالات الناجحة على الموقع الإلكتروني والناتجة من أجهزة iOS بدءًا من iOS14.
`userIdentifiers[]`	`object (UserIdentifier)` معرّفات المستخدمين المرتبطة بهذه الإحالة الناجحة. لا يتم دعم سوى تعديلات البريد الإلكتروني المجزّأة وتجزئة رقم الهاتف المجزّأ لعمليات تحميل الإحالات الناجحة. الحد الأقصى لعدد معرّفات المستخدمين لكل إحالة ناجحة هو 5.
`gclid`	`string` معرّف النقرة من Google (gclid) المرتبط بهذه الإحالة الناجحة.
`conversionAction`	`string` اسم المورد لإجراء الإحالة الناجحة المرتبط بهذه الإحالة الناجحة.
`conversionDateTime`	`string` تاريخ وقت حدوث الإحالة الناجحة. التنسيق هو "yyyy-mm-dd hh:mm:ss+\|-hh:mm"، على سبيل المثال، "01-01-2019 12:32:45-08:00".