الوصول إلى بيانات Oracle Sales Automation باستخدام خدمات RESTful
تحتوي كل واجهة برمجة تطبيقات على كائنات Oracle Sales Automation قياسية وكل كائن مرتبط بموارد REST أو مجموعة الموارد. على سبيل المثال، في واجهة برمجة تطبيقات RESTful، يتم استخدام نقطة انتهاء مورد Opportunities لتتبع معلومات حول عملية بيع محتملة. ومع ذلك، قبل استخدام خدمات ويب Oracle Sales Automation RESTful، يجب أن تأخذ في الاعتبار متطلبات الأمان للحصول على الوصول، وكذلك تحديد خدمات الويب التي يجب استخدامها، بالإضافة إلى الأساليب المدعومة المقابلة وهياكل الحمولة المتوقعة.
حول الموارد في واجهات برمجة تطبيقات Oracle Sales Automation RESTful
يوفر Oracle Sales Automation مجموعة من موارد REST للوحدات القياسية والمخصصة.
أحد المفاهيم المهمة في أي واجهة برمجة تطبيقات RESTful هو المورد. المورد هو كائن من نوع (على سبيل المثال، الفرص) والبيانات المرتبطة والعلاقات مع الموارد الأخرى ومجموعة من الأساليب التي تعمل عليه. يتم تنظيم هذه الموارد بطريقة هرمية تتضمن:
-
المورد الأساسي: يتوافق مع كائن منطقي، مثل فرصة مبيعات أو فرصة تسويقية.
-
المورد (الموردون) الفرعي: هذه هي الموارد التي تنتمي إلى مورد رئيسي؛ على سبيل المثال جهة اتصال لفرصة مبيعات.
-
مورد قائمة القيم: قائمة بالقيم الصالحة التي يمكن استخدامها عند تعيين قيمة لحقل. يوجد نوعان: بحث (قائمة ثابتة) أو ديناميكي (على أساس السياق).
في واجهة برمجة تطبيقات Oracle Sales Automation RESTful، يوجد نوعان من الموارد: مورد واحد أو مورد مجموعة. يمكن أن يمثل المورد الواحد كيانًا واحدًا مثل الموظف أو أمر الشراء، بينما يمكن أن يكون مورد التحصيل أكثر شمولاً مثل قائمة الموظفين أو قائمة أوامر الشراء التي يمكن تقسيمها إلى صفحات.
حول دعم REST للوحدات المخصصة
يتضمن Oracle Sales Automation كائنات قياسية تمثل العديد من احتياجات الأعمال وسيناريوهاتها. ومع ذلك، بالإضافة إلى الكائنات القياسية، يمكنك استخدام أداة Application Composer لتكوين كل من الكائنات المخصصة ذات المستوى الأعلى والكائنات المخصصة الفرعية إذا كانت لديك حاجة عمل فريدة.
يعد Application Composer أداة مستندة إلى المستعرض يمكن لمحللي الأعمال والمسئولين (وليس المطورين فقط) استخدامها لتخصيص Oracle Sales Automation. باستخدام هذه الأداة، يمكنك إجراء أنواع تغييرات نموذج البيانات التي تم إجراؤها في الماضي فقط من قبل المطورين. في أداة Application Composer، يمكنك إجراء تغييرات بشكل سريع وتصبح متاحة للاستخدام على الفور دون الحاجة إلى تسجيل الدخول مرة أخرى إلى التطبيق، ويتضمن ذلك تكوين كائنات مخصصة يمكن إضافتها إلى واجهة برمجة تطبيقات Oracle Sales Automation RESTful.
تلميحات الأداء
للحصول على أفضل أداء من واجهات برمجة تطبيقات REST لـ Oracle Fusion Sales Cloud، اتبع هذه النصائح.
- استعلم فقط عن البيانات التي تحتاجها.
- استعلم عن البيانات فقط، وليس بيانات التعريف.
salesApi/resources/latest/opportunitiessalesApi/resources/latest/opportunities?fields=Name,OptyNum&onlyData=trueالبحث عن موارد RESTful باستخدام نقاط الانتهاء "وصف"
يمكنك الحصول على تفاصيل محددة حول واجهات برمجة تطبيقات Oracle Sales Automation RESTful المختلفة عن طريق إرسال طلب HTTP GET يُرجع كائن JSON يحتوي على معلومات المورد وبيانات التعريف التكميلية.
الحصول على نقاط نهاية الخدمة لـ RESTful Web Services
يمكنك استنتاج اسم نقطة انتهاء Oracle Sales Automation RESTful Web Service عن طريق تحديد اسم الخدمة بدلاً من الكلمة الأساسية "describe" في عنوان URL لواجهة برمجة التطبيقات.
حول عمليات REST وهياكل البيانات المنقولة
توفر خدمة الويب RESTful لكل كائن Oracle Sales Automation قياسي العديد من عمليات التكوين والقراءة والتحديث والحذف (CRUD).
يمكنك تنفيذ الأساليب القياسية التالية للتفاعل مع مورد مفرد أو مجموعة موارد من خلال عناوين URL الخاصة بها:
| الأسلوب | متاح لمورد مفرد | متاح لمجموعة الموارد |
|---|---|---|
| إحضار | ص | ن |
| إرسال | ن | ص |
| تصحيح | ص | ن |
| حذف | ص | ن |
حول أسلوب الإحضار
استخدم هذا الأسلوب للاستعلام عن المعلومات واسترجاعها. على أن المعلمات المستخدمة في الاستعلام لتنقيح البحث أو تضييق نطاق النتائج في مورد مفرد تختلف عن تلك المستخدمة في مجموعة الموارد.
معاملات كل من الموارد الفردية وموارد التجميع
يتم استخدام المعلمات التالية في أسلوب الاستعلام عن مورد مفرد بالإضافة إلى مورد تجميع:
| المعلمة | صيغة | الوصف |
|---|---|---|
expand |
أو
|
إرجاع المورد الرئيسي بما في ذلك المورد الفرعي الخاص به. بشكل افتراضي لا يتم إرجاع أي عنصر فرعي. |
fields |
fields=<FieldName1>,<FieldName2>... |
قم بتحديد حقل (حقول) محدد فقط تكون المعلومات مطلوبة له. |
onlyData |
أو
|
استرجاع البيانات فقط وليس أي عناوين URL للموارد. بشكل افتراضي، يتم إرجاع كل عناوين URL الفرعية للمورد. |
معاملات موارد التحصيل
تستخدم طريقة GET لمورد التجميع المعلمات التي تمت مناقشتها أعلاه بالإضافة إلى المعلمات التالية:
| المعلمة | صيغة | الوصف |
|---|---|---|
limit |
|
عدد صحيح أكبر من 0 يحدد الحد الأقصى لعدد العناصر التي يرجعها الخادم. في حالة عدم تحديد قيمة حد، سيستخدم الخادم قيمة حد افتراضية. |
offset |
offset=<Integer> |
قيمة عدد صحيح تحدد فهرس العنصر الأول المطلوب إرجاعه. يبدأ مؤشر الإزاحة عند 0. |
q |
|
حدد شرط ترشيح لتقييد العناصر التي يتم إرجاعها في المجموعة. تحتوي قيمة معلمة الاستعلام هذه على تعبير واحد أو أكثر مفصولة بـ ";". على سبيل المثال العوامل المدعومة:
الأحرف الخاصة:
|
totalResults |
أو
|
قيمة منطقية تحدد ما إذا كان سيتم إرجاع إجمالي عدد العناصر المطابقة لمعلمة الاستعلام "q".
|
orderBy |
|
تحديد ترتيب الأصناف المرتجعة في حمولة الاستجابة. قيمة معلمة الاستعلام هي سلسلة مفصولة بفاصلة من أسماء الحقول، ويتبع كل منها بعلامة نقطتين وكلمة الأساس في حالة عدم التحديد، يقوم الخادم بإرجاع العناصر بترتيب تصاعدي. |
finder |
|
استخدام "استعلام" معرف مسبقًا يشتمل على معلمات خاصة به. على سبيل المثال، يشتمل مورد |
dependency |
|
يُستخدم لتتالي موارد قائمة القيم. على سبيل المثال، إذا كان للمورد Location حقل State، فسيتم اشتقاق هذه القيم من مورد States آخر يعرض قائمة بالدول لبلد معين (موقع). إذا كان الموقع على سبيل المثال: الولايات المتحدة والولاية هي كاليفورنيا. يحتوي مورد الولايات على قائمة بجميع الولايات المتحدة، ولكن إذا قام المستخدم في صفحة الويب بتغيير المنطقة اللغوية إلى البرازيل، فستكون طريقة استرداد جميع الولايات البرازيلية بمكالمة كهذه:
|
حول طريقة الإرسال
استخدم هذه الطريقة لتكوين عنصر جديد. عنوان نوع وسائط الطلب هو:
application/vnd.oracle.adf.resourceitem+jsonعلى سبيل المثال، لتكوين فرصة مبيعات جديدة ضمن مورد Opportunities، يقوم الطلب بتمرير معلمة اسم الفرصة الجديدة في كائن JSON:
{
"Name" : "New Opportunity Name"
}نص الاستجابة لكائن JSON الذي تم إرجاعه بواسطة طلب POST سيكون على النحو التالي:
{
BudgetAvailableDate: null
BudgetedFlag: false
PrimaryOrganizationId: 204
ChampionFlag: false
CreatedBy: "SALES_ADMIN"
CreationDate: "2015-06-04T03:08:27-07:00"
CurrencyCode: "USD"
SalesMethodId: 100000012430001
SalesStageId: 100000012430007
Name: "New Opportunity Name"
OptyId: 300100111705686
OptyNumber: "CDRM_332708"
OwnerResourcePartyId: 3807
StatusCode: "OPEN"
PrimaryRevenueId: 300100111705687
SalesMethod: "Standard Sales Process"
SalesStage: "01 - Qualification"
DescriptionText: "Looking for the Right Contacts, Characteristics,
Determining the Need, Budget and Sponsor"
AverageDaysAtStage: 30
MaximumDaysInStage: 800
PhaseCd: "QUALIFICATION-DISCOVERY"
QuotaFactor: 3
RcmndWinProb: 0
StageStatusCd: "OPEN"
StgOrder: 1
EffectiveDate: "2015-06-24"
Revenue: 0
WinProb: 0
PartyName1: "Charles Taylor"
DownsideAmount: 0
UpsideAmount: 0
EmailAddress: "firstname lastname@orcl.com"
ExpectAmount: 0
ForecastOverrideCode: "CRITERIA"
SalesChannelCd: "ZPM_DIRECT_CHANNEL_TYPES"
…
}حول أسلوب التصحيح
استخدم هذه الطريقة لإجراء تحديثات جزئية على مورد. سيتم تحديث الحقول الموجودة في نص الطلب فقط.
نوع وسائط الطلب هو:
application/vnd.oracle.adf.resourceitem+jsonعلى سبيل المثال، لتحديث فرصة موجودة من مورد Oppurtunities، يقوم طلب HTTP PATCH بتمرير كائن JSON التالي كنص الطلب:
{
"Name": "Opportunity Name Updated"
}الاستجابة من هذا الطلب هي كائن JSON مشابه لذلك:
{
BudgetAvailableDate: null
BudgetedFlag: false
PrimaryOrganizationId: 204
ChampionFlag: false
CreatedBy: "SALES_ADMIN"
CreationDate: "2015-06-04T03:08:27-07:00"
CurrencyCode: "USD"
SalesMethodId: 100000012430001
SalesStageId: 100000012430007
Name: "Opportunity Name Updated"
OptyId: 300100111705686
OptyNumber: "CDRM_332708"
OwnerResourcePartyId: 3807
StatusCode: "OPEN"
PrimaryRevenueId: 300100111705687,
SalesMethod: "Standard Sales Process"
SalesStage: "01 - Qualification"
DescriptionText: "Looking for the Right Contacts, Characteristics,
Determining the Need, Budget and Sponsor"
AverageDaysAtStage: 30
MaximumDaysInStage: 800
PhaseCd: "QUALIFICATION-DISCOVERY"
QuotaFactor: 3
RcmndWinProb: 0
StageStatusCd: "OPEN"
StgOrder: 1
EffectiveDate: "2015-06-24"
Revenue: 0
WinProb: 0
PartyName1: "Charles Taylor"
DownsideAmount: 0
UpsideAmount: 0
EmailAddress: "firstname_lastname@orcl.com"
ExpectAmount: 0
ForecastOverrideCode: "CRITERIA"
SalesChannelCd: "ZPM_DIRECT_CHANNEL_TYPES"
…
}حول أسلوب الحذف
استخدم هذا الأسلوب لحذف مورد. لا يتطلب نص طلب.
على سبيل المثال، لحذف كائن فرصة من المورد Opportunities، يجب تقديم طلب DELETE مباشرةً إلى معرف URI الخاص بمورد Opportunity الفرعي المطلوب حذفه، دون تمرير أي معلمة إليه:
https://<crm_server:PortNumber>/salesApi/resources/latest/opportunities/<OpportunityNumber>
حول أساليب الإجراء المخصصة
في بعض الأحيان، يعرض المورد إجراءً مخصصًا لا يتناسب مع معيار CRUD. يتم دائمًا استدعاء إجراء مخصص باستخدام POST (للمجموعات الفردية ومجموعات الموارد) ونوع وسائط الطلب الخاص به هو:
application/vnd.oracle.adf.action+jsonنوع وسائط الاستجابة هو:
application/vnd.oracle.adf.actionresult+jsonعلى سبيل المثال، في Oracle Sales Automation، يشتمل مورد leads ضمن https://<crm_server:portNumber>/salesApi/resources/latest/describe/leads/ على إجراء مخصص لتحويل فرصة تسويقية إلى فرصة مبيعات باسم: convertLeadToOpty.
{
"name" : "convertLeadToOpty",
"parameters" : [ {
"name" : "leadId",
"type" : "number",
"mandatory" : false
} ],
"resultType" : "string",
"method" : "POST",
"requestType" : [ "application/vnd.oracle.adf.action+json" ],
"responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ]
},فكر في إجراء مخصص كسلسلة من الخطوات أو عملية أو مزيج من عمليات CRUD المختلفة لتحقيق هدف محدد. في المثال أعلاه، يتعين على نص طلب إجراء مخصص تمرير "الاسم" الذي سيكون اسم الإجراء المخصص (أي convertLeadToOpty)، وبشكل اختياري مصفوفة بمعلمات المدخلات للإجراء المخصص (أي leadId).
عادة ما يحتوي نص JSON لطلب POST على:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"title": "Action execution representation.",
"description": "Represents the action execution and its
parameters.",
"properties": {
"name": {
"type": "string",
"description": "Action name."
},
"parameters": {
"type": "array",
"description": "Parameter name/value pair.",
}
},
"required": [
"name"
]
}يحتوي كائن استجابة JSON على نتيجة أسلوب الإجراء المخصص في حقل "النتائج".
حول الدعم الدفعي
لتحسين الأداء، يمكن دمج عمليات متعددة في طلب HTTP واحد عن طريق إرسال كائن JSON يحتوي على حقل بالاسم: "parts" كصفيف كائنات. يحتوي كل كائن داخل المصفوفة على معرف فريد ومسار نسبي للمورد وعملية وحمولة اختياريًا.
مخطط JSON لطلب HTTP هو:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"title": "Batch execution",
"description": "Group multiple requests together ('part').",
"definitions": {
"Part": {
"type": "object",
"allOf": [
{
"properties": {
"id": {
"type": "string",
"description": "An identification
provided by the client to distinguish each part provided in the
batch request."
},
"path": {
"type": "string",
"description": "Resource's location."
},
"operation": {
"type": "string",
"enum": [
"get",
"create",
"update",
"replace",
"delete"
],
"description": "The operation that will
be performed."
},
"preconditionSucceeded": {
"type": "boolean",
"description": "This attribute is set in
the batch response only when ifMatch or ifNoneMatch are provided in
the request. It will be 'true' if the precondition
(ifMatch/ifNoneMatch) was satisfied, otherwise 'false'."
},
"payload": {
"oneOf": [
{
"$ref": "resource-item.json",
"description": "The payload that
will be used in the operation. Example: a resource instance should
be provided in order to execute a 'create'."
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"path",
"operation"
]
}
],
"anyOf": [
{
"properties": {
"ifMatch": {
"type": "string",
"description": "This attribute is
analogous to the If-Match header. It represents a precondition to
execute this operation. The value can be null (same effect of 'If-
Match: *') or an array of resource versions."
}
}
},
{
"properties": {
"ifNoneMatch": {
"type": "string",
"description": "This attribute is
analogous to the If-None-Match header. It represents a precondition
to execute this operation. The value can be null (same effect of
'If-None-Match: *') or an array of resource versions."
}
}
}
],
"description": "Represents a request."
}
},
"properties": {
"parts": {
"type": "array",
"items": {
"$ref": "#/definitions/Part"
},
"description": "Array that represents multiple
requests."
}
},
"required": [
"parts"
]
}
على سبيل المثال، سيقوم الطلب التالي بسحب موظف موجود وتحديث موظف آخر:
POST /myapi/resources/latest/hremployees HTTP/1.1
Host: example.oracle.com
Content-type:application/vnd.oracle.adf.batch+json
{
"parts": [
{
"id": "part1",
"path": "/latest/hremployees/101",
"operation": "get"
},
{
"id": "part2",
"path": "/latest/hremployees/102",
"operation": "update",
"payload": {
"Salary": 18000
}
}
]
}
تستخدم استجابة الطلب السابق نفس نوع الوسائط الخاص بالطلب وتُرجع كائن JSON مثل:
{"parts":[
{
"id":"part1",
"path":"/latest/hremployees/101",
"operation":"get",
"payload" : {
"EmployeeId" : 101
…
},
{
"id" : "part2",
"path" : "/latest/hremployees/102",
"operation" : "update",
"payload" : {
"EmployeeId" : 102,
} ]}اختبار طلب خدمة ويب Oracle Sales Automation RESTful
لاختبار واجهة برمجة تطبيقات RESTful والحصول على البيانات المطلوبة، يمكنك استخدام أداة سطر أوامر cURL لنقل البيانات من خادم أو إليه باستخدام أحد البروتوكولات المدعومة مثل HTTP أو HTTPS.