ضبط سياسة تسجيل المعاملات

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

اضبط سياسات تسجيل المعاملات لكل منتج من منتجات واجهة برمجة التطبيقات في حزمة منتجات واجهة برمجة التطبيقات، كما هو موضّح في الأقسام التالية.

مقدمة

تتيح سياسة تسجيل المعاملات تحقيق الربح من خلال تسجيل مَعلمات المعاملات والسمات المخصّصة. تحتاج ميزة تحقيق الربح إلى هذه المعلومات لتنفيذ عمليات تحقيق الربح، مثل تطبيق خطط الأسعار.

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

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

بالإضافة إلى تحديد سمات المعاملات في سياسة تسجيل المعاملات، يمكنك تحديد معايير نجاح المعاملات لتحديد وقت نجاح المعاملة (لأغراض تحصيل الرسوم). للاطّلاع على أمثلة حول ضبط معايير نجاح المعاملات، راجِع أمثلة حول ضبط معايير نجاح المعاملات في سياسة تسجيل المعاملات. يمكنك أيضًا تحديد سمات مخصّصة لمنتج API (الذي تستند إليه رسوم خطة الأسعار).

ضبط سياسة تسجيل المعاملات

انتقِل إلى صفحة "حِزم المنتجات"، كما هو موضّح أدناه.

إعداد سمات المعاملات

في قسم سمات المعاملة، حدِّد المعايير التي تشير إلى نجاح معاملة تحقيق الربح.

1. في حقل معايير نجاح المعاملة، حدِّد التعبير استنادًا إلى قيمة السمة "الحالة" (الموضّحة أدناه) لتحديد وقت نجاح المعاملة (لأغراض تحصيل الرسوم). يتم تسجيل المعاملات غير الناجحة (أي التي لا تستوفي المعايير الواردة في التعبير)، ولكن لا يتم تطبيق خطط الأسعار عليها. على سبيل المثال:

   txProviderStatus == 'OK'

2. تحتوي السمة الحالة على القيمة المستخدَمة في التعبير الذي تم ضبطه في حقل معايير نجاح المعاملة. اضبط سمة الحالة من خلال تحديد الحقول التالية:

   الحقل	الوصف
   مورد واجهة برمجة التطبيقات	أنماط معرّف الموارد المنتظم (URI) المحدّدة في منتج واجهة برمجة التطبيقات والتي سيتم استخدامها في تحديد المعاملات التي يتم تحقيق الربح منها
   موقع الردّ	موقع الرد الذي تم تحديد السمة فيه تشمل القيم الصالحة: متغيّر التدفق والعنوان ونص JSON ونص XML.
   القيمة	قيمة الردّ لتحديد أكثر من قيمة واحدة، انقر على + إضافة x (على سبيل المثال، + إضافة متغيّر سير العمل).

3. لضبط سمات المعاملات الاختيارية، فعِّل زر التبديل استخدام السمات الاختيارية واضبط أيًا من سمات المعاملات المحدّدة في الجدول التالي.

   السمة	الوصف
   السعر الإجمالي	تنطبق هذه السمة فقط على خطط الأسعار التي تستخدم نموذج مشاركة الأرباح. بالنسبة إلى خطط الأسعار هذه، يجب توفير "السعر الإجمالي" أو "السعر الصافي". تأكَّد من أنّ القيمة الرقمية معبَّر عنها كنوع سلسلة. تمثّل هذه السمة السعر الإجمالي للمعاملة. بالنسبة إلى خطط مشاركة الأرباح، عليك تسجيل سمة "السعر الإجمالي" أو سمة "السعر الصافي". تختلف السمة المطلوبة حسب أساس حصة الإيرادات. على سبيل المثال، يمكنك إعداد خطة معدّل مشاركة الأرباح استنادًا إلى السعر الإجمالي للمعاملة. في هذه الحالة، يجب ملء حقل "السعر الإجمالي".
   السعر الصافي	تنطبق هذه السمة فقط على خطط الأسعار التي تستخدم نموذج مشاركة الأرباح. بالنسبة إلى خطط الأسعار هذه، يجب توفير "السعر الإجمالي" أو "السعر الصافي". تأكَّد من أنّ القيمة الرقمية معبَّر عنها كنوع سلسلة. تمثّل هذه السمة السعر الصافي للمعاملة. بالنسبة إلى خطط مشاركة الأرباح، عليك تسجيل إما حقل "السعر الصافي" أو حقل "السعر الإجمالي". يعتمد الحقل المطلوب على أساس حصة الإيرادات. على سبيل المثال، يمكنك إعداد خطة معدّل مشاركة الأرباح استنادًا إلى السعر الصافي للمعاملة. في هذه الحالة، يجب ملء حقل "السعر الصافي".
   العملة	هذه السمة مطلوبة لخطط الأسعار التي تستخدم نموذج مشاركة الأرباح. نوع العملة التي تنطبق على المعاملة.
   رمز الخطأ	رمز الخطأ المرتبط بالمعاملة. ويوفّر معلومات إضافية حول المعاملة التي تعذّر إتمامها.
   وصف العنصر	وصف المعاملة
   الضريبة	لا تنطبق هذه السمة إلا على نماذج مشاركة الأرباح، وفقط إذا تم تسجيل مبلغ الضريبة في طلبات البيانات من واجهة برمجة التطبيقات. تأكَّد من التعبير عن القيمة الرقمية كنوع سلسلة. مبلغ الضريبة على عملية الشراء السعر الصافي + الضريبة = السعر الإجمالي

على سبيل المثال، من خلال ضبط القيم التالية، تحصل تحقيق الربح على قيمة متغيّر التدفق من استجابة الرسالة في متغيّر يُسمى response.reason.phrase. إذا كانت القيمة OK، وتم ربط سياسة التحقّق من حدود تحقيق الربح بطلب ProxyEndpoint لخادم وكيل واجهة برمجة التطبيقات، سيتم احتساب عملية تحقيق الربح كمعاملة.

ضبط السمات المخصّصة

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

يتم تخزين كل سمة من هذه السمات في سجلّ المعاملات الذي يمكنك الاستعلام عنه. تظهر هذه السمات أيضًا عند إنشاء خطة أسعار (لتتمكّن من اختيار سمة واحدة أو أكثر تستند إليها أسعار الخطة).

يمكنك تضمين السمات المخصّصة المحدّدة في سياسة تسجيل المعاملات في تقارير ملخّص الأرباح، كما هو موضّح في تضمين سمات المعاملات المخصّصة في تقارير ملخّص الأرباح.

لضبط السمات المخصّصة، فعِّل خيار استخدام السمات المخصّصة وحدِّد ما يصل إلى 10 سمات مخصّصة. لكل سمة مخصّصة تُدرجها في سياسة تسجيل المعاملات، عليك تحديد المعلومات التالية.

ربط الموارد بمعرّف معاملة فريد

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

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

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

لضبط السمات المخصّصة، فعِّل خيار استخدام معرّفات معاملات فريدة واربط المعاملات. بالنسبة إلى كل معاملة، عليك تحديد مرجع وموقع استجابة وقيمة سمة مرتبطة بالقيم المقابلة في المعاملات الأخرى.

على سبيل المثال، لنفترض أنّ طلب البيانات من واجهة برمجة التطبيقات Reserve وطلب البيانات من واجهة برمجة التطبيقات Charge مرتبطان على النحو التالي: يتوافق الحقل المسمّى session_id في عنوان الاستجابة من واجهة برمجة التطبيقات Reserve مع عنوان الاستجابة المسمّى reference_id من واجهة برمجة التطبيقات Charge. في هذه الحالة، يمكنك ضبط الإدخالات في قسم "ربط المراجع بمعرّف معاملة فريد" على النحو التالي:

ضبط عمليات ردّ الأموال

في قسم عمليات ردّ الأموال، يمكنك تحديد السمات التي تستخدمها ميزة تحقيق الربح لمعالجة عمليات ردّ الأموال.

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

لضبط عمليات ردّ الأموال، فعِّل خيار استخدام سمات ردّ الأموال وحدِّد تفاصيل ردّ الأموال:

1. حدِّد معايير ردّ الأموال من خلال تحديد الحقول التالية:

   الحقل	الوصف
   موقع الردّ	تمثّل هذه السمة مصدر معاملة إرجاع المال. إذا كان منتج واجهة برمجة التطبيقات يوفّر موارد متعددة، يمكنك اختيار المورد الذي ينفّذ عملية ردّ الأموال فقط.
   معايير نجاح عملية ردّ الأموال	تعبير يستند إلى قيمة السمة "الحالة" (الموضّحة أدناه) لتحديد وقت نجاح معاملة إرجاع المال (لأغراض تحصيل الرسوم). يتم تسجيل معاملات ردّ الأموال غير الناجحة (أي التي لا تستوفي المعايير الواردة في التعبير)، ولكن لا يتم تطبيق خطط الأسعار عليها. على سبيل المثال: txProviderStatus == 'OK'

2. اضبط سمة الحالة من خلال تحديد الحقول التالية:

   الحقل	الوصف
   موقع الردّ	موقع الرد الذي تم تحديد السمة فيه تشمل القيم الصالحة: متغيّر التدفق والعنوان ونص JSON ونص XML.
   القيمة	قيمة الردّ لتحديد أكثر من قيمة واحدة، انقر على + إضافة x (على سبيل المثال، + إضافة متغيّر سير العمل).

3. اضبط السمة رقم تعريف العنصر الرئيسي من خلال تحديد الحقول التالية:

   الحقل	الوصف
   موقع الردّ	موقع الرد الذي تم تحديد السمة فيه تشمل القيم الصالحة: متغيّر التدفق والعنوان ونص JSON ونص XML.
   القيمة	معرّف المعاملة التي تتم معالجة عملية ردّ الأموال لها. على سبيل المثال، إذا اشترى مستخدم منتجًا ثم طلب استرداد الأموال، سيكون معرّف المعاملة الرئيسية هو معرّف معاملة الشراء. لتحديد أكثر من قيمة واحدة، انقر على + إضافة x (على سبيل المثال، + إضافة متغيّر سير العمل).

4. لضبط سمات ردّ الأموال الاختيارية، فعِّل زر استخدام سمات ردّ الأموال الاختيارية وعدِّل السمات. تتشابه سمات ردّ الأموال الاختيارية مع سمات المعاملات الاختيارية، كما هو موضّح في إعداد سمات المعاملات.

إدارة سياسات تسجيل المعاملات باستخدام واجهة برمجة التطبيقات

توضّح الأقسام التالية كيفية إدارة سياسات تسجيل المعاملات باستخدام واجهة برمجة التطبيقات.

إنشاء سياسة تسجيل المعاملات باستخدام واجهة برمجة التطبيقات

يمكنك تحديد سياسة تسجيل المعاملات كسمة لمنتج API. تحدّد قيمة السمة ما يلي:

• لاحقة معرّف الموارد المنتظم (URI) لمورد المنتج الذي تم ربط سياسة تسجيل المعاملات به. يتضمّن اللاحقة متغيّر نمط محاطًا بأقواس معقوفة. يتم تقييم المتغيّر pattern من خلال "خدمات Google API" في وقت التشغيل. على سبيل المثال، يتضمّن لاحقة URI التالية متغيّر النمط {id}.

  /reserve/{id}**

  في هذه الحالة، تقيِّم "خدمات واجهة برمجة التطبيقات" لاحقة URI الخاصة بالمرجع على النحو التالي: /reserve متبوعة بأي دليل فرعي يبدأ بمعرّف يحدّده مقدّم واجهة برمجة التطبيقات.

• تمثّل هذه السمة المورد في الردّ الذي تم إرفاقها به. يمكن أن يتضمّن منتج واجهة برمجة التطبيقات موارد متعددة، ويمكن أن يتضمّن كل مورد سياسة تسجيل معاملات مرفقة بردّ من هذا المورد.
• سياسة متغيّر الاستخراج التي تتيح لسياسة تسجيل المعاملات استخراج المحتوى من رسالة ردّ لمعلمات المعاملة التي تريد تسجيلها.

يمكنك إضافة سمة سياسة تسجيل المعاملات إلى منتج واجهة برمجة تطبيقات من خلال إصدار طلب PUT إلى واجهة برمجة التطبيقات الإدارية https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (وليس إلى واجهة برمجة تطبيقات تحقيق الربح).

تحديد معايير نجاح المعاملة باستخدام واجهة برمجة التطبيقات

يمكنك تحديد معايير نجاح المعاملة لتحديد وقت نجاح المعاملة (لأغراض تحصيل الرسوم). يتم تسجيل المعاملات غير الناجحة (أي التي لا تستوفي المعايير في التعبير)، ولكن لا يتم تطبيق خطط الأسعار عليها. للاطّلاع على أمثلة حول وضع معايير نجاح المعاملات، راجِع أمثلة حول وضع معايير نجاح المعاملات في سياسة تسجيل المعاملات.

يمكنك تحديد معايير نجاح المعاملة كسمة لمنتج API. يمكنك إجراء ذلك من خلال إرسال طلب PUT إلى واجهة برمجة التطبيقات الإدارية https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (وليس إلى واجهة برمجة التطبيقات لتحقيق الربح).

على سبيل المثال، في الطلب التالي، تكون المعاملة ناجحة إذا كانت قيمة txProviderStatus هي success (تم تمييز المواصفات ذات الصلة بمعايير نجاح المعاملة).

$ curl -H "Content-Type: application/json" -X PUT -d \ 
'{
        "apiResources": [
        "/reserve/{id}**"       
        ],
        "approvalType": "auto",
        "attributes": [                         
        {
                "name": "MINT_TRANSACTION_SUCCESS_CRITERIA",
                "value": "txProviderStatus == 'OK'"
        }
        ],
        "description": "Payment",
        "displayName": "Payment",
        "environments": [
        "dev"
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
        ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

تحديد السمات المخصّصة باستخدام واجهة برمجة التطبيقات

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

يمكنك تحديد السمات المخصّصة كسمات لمنتج API. يمكنك إجراء ذلك من خلال إرسال طلب PUT إلى واجهة برمجة التطبيقات الإدارية https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (وليس إلى واجهة برمجة التطبيقات لتحقيق الربح).

لكل سمة مخصّصة تضيفها إلى منتج API، عليك تحديد اسم وقيمة للسمة. يجب أن يكون الاسم بالتنسيق MINT_CUSTOM_ATTRIBUTE_{num}، حيث {num} عدد صحيح.

على سبيل المثال، يحدّد الطلب التالي ثلاث سمات مخصّصة.

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
        "apiResources": [
        "/reserve/{id}**",
        "/charge/{id}**"
        ],
        "approvalType": "auto",
        "attributes": [
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_1",
                "value": "test1"
        },
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_2",
                "value": "test2"
        }
 
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
                ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

أمثلة على ضبط معايير نجاح المعاملات في سياسة تسجيل المعاملات

يقدّم الجدول التالي أمثلة على المعاملات الناجحة وغير الناجحة، استنادًا إلى تعبير معايير نجاح المعاملة والقيمة txProviderStatus التي تعرضها واجهة برمجة التطبيقات للخادم الوكيل. ‫txProviderStatus هو المتغيّر الداخلي الذي تستخدمه ميزة تحقيق الربح لتحديد ما إذا كانت المعاملة ناجحة.