دروس API: قراءة البيانات الموجودة في السجل

نوصي المطورين باختبار Public API في ملف خادم اختبار وضع الحماية قبل استخدام نسخة الإنتاج. فيما يلي خطوات كيفية التسجيل للحصول على بيانات اعتماد API العامة في كل من بيئات Sandbox والإنتاج.

• تسجيل الدخول الى حسابك ORCID سجل:
  خادم الإنتاج: https://orcid.org/signin
  خادم اختبار Sandbox: https://sandbox.orcid.org/signin
• انقر فوق اسمك في الزاوية اليمنى العليا
• انقر ادوات المطورين من خيار القائمة
  ملحوظة: من أجل الوصول إلى أدوات المطور ، يجب عليك التحقق من عنوان بريدك الإلكتروني. إذا لم تكن قد قمت بالفعل بالتحقق من عنوان بريدك الإلكتروني ، فسيُطلب منك القيام بذلك قبل أن تتمكن من التسجيل للحصول على بيانات اعتماد API العامة
• اقرأ ووافق على "ORCID شروط خدمة واجهات برمجة التطبيقات العامة
• انقر فوق "التسجيل في ORCID "الزر "بيانات اعتماد واجهة برمجة التطبيقات العامة".

استكمال نموذج تفاصيل الطلب

• بمجرد التسجيل في بيانات اعتماد API العامة الخاصة بك ، سيتم توجيهك مرة أخرى إلى Developer Tools (https://orcid.org/developer-tools or https://sandbox.orcid.org/developer-tools).
• تحتاج إلى إكمال نموذج تفاصيل الطلب المقدم لتسجيل طلب جديد.
  • الاسم: اسم التطبيق الخاص بك. سيتم عرض هذا للمستخدمين عند منحهم إذن تطبيقك للحصول على ملفات ORCID معرف ، وسيتم عرضه في ملفات قائمة المنظمات الموثوقة. نوصي باستخدام اسم مؤسستك أو خدمتك (مثل اسم المجلة).
  • عنوان URL للتطبيق: موقع الويب الذي يمكن للمستخدم زيارته لمعرفة المزيد عن تطبيقك. سيتم عرض هذا أيضًا في ملفات قائمة المنظمات الموثوقة.
  • وصف التطبيق: معلومات حول التطبيق الذي تقوم بتطويره وكيف ستستخدم المستخدم ORCID هوية شخصية. سيتم عرض هذا للمستخدمين على شاشة OAuth.

إضافة إعادة توجيه URIs

بمجرد أن يصرح المستخدم للتطبيق الخاص بك ، سيتم إعادته إلى URI الذي تحدده. يجب عليك تقديم URIs مسبقًا وإلا سيواجه مستخدمو الدمج خطأ.

• أدخل عنوان URI لإعادة التوجيه في المربع المتوفر
• إذا كنت بحاجة إلى إدخال أكثر من عنوان URI لإعادة التوجيه ، فانقر فوق "إضافة عنوان URI آخر لإعادة التوجيه"

يرجى الملاحظة:

• فقط عناوين HTTPS URI يتم قبولها في الإنتاج
• المجالات المسجلة يجب تتطابق تمامًا مع المجالات المستخدمة ، بما في ذلك المجالات الفرعية
• قم بتسجيل جميع عناوين URL المعاد توجيهها بالكامل حيثما أمكن ذلك. هذا هو الخيار الأكثر أمانًا وما نوصي به. لمزيد من المعلومات حول إعادة توجيه URIs ، يرجى الاطلاع على إعادة توجيه الأسئلة الشائعة لـ URI

حفظ التطبيق الخاص بك

بمجرد إكمال نموذج الطلب وإضافة URIs الخاصة بإعادة التوجيه ، يمكنك حفظ طلبك.

• انقر فوق "حفظ طلبي وإنشاء معرف العميل والسر الخاص بي"

سيتم توجيهك مرة أخرى إلى صفحة أدوات المطور والتي ستتضمن الآن بيانات اعتماد عميل API العام

تحديث بيانات الاعتماد الخاصة بك

إجراء تغيير على معلومات التطبيق الخاص بك أمر بسيط للغاية.

• قم بتحرير المعلومات ذات الصلة ثم انقر فوق "حفظ التطبيق"

استخدم أوراق اعتمادك

الآن بعد أن حصلت على بيانات الاعتماد الخاصة بك ، حان الوقت لبدء استخدام ملف ORCID API العامة!

يرجى ملاحظة أنه يمكننا نقل بيانات الاعتماد الخاصة بك إلى عضو API إذا أصبحت ORCID عضو فى المستقبل.

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

ملاحظات: إذا كنت تستخدم ORCID نظام مزود الخدمة المعتمد الذي يدعم بالفعل ORCID، فأنت لا تحتاج إلى التسجيل للحصول على بيانات اعتماد Sandbox API إلا إذا كنت ترغب في تجربة ORCID وظيفة التكامل داخل بيئة Sandbox. 

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

إنشاء حساب اختباري

من أجل اختبار ORCID استدعاءات API و API ، مثل قراءة وإضافة معلومات إلى ملف ORCID سجل ، سوف تحتاج أيضًا إلى إنشاء اختبار ORCID سجل في الصندوق الرمل. يمكن القيام بذلك من خلال واجهة المستخدم ، كما هو الحال في الإنتاج ORCID التسجيل. اذهب إلى https://sandbox.orcid.org/register وقم بالتسجيل للحصول على حساب.

عناوين البريد الإلكتروني Mailinator

يرسل خادم Sandbox رسائل البريد الإلكتروني فقط إلى Mailinator (@ mailinator.com) عناوين البريد الإلكتروني من أجل عدم إرسال بريد عشوائي على خوادم عن غير قصد. لن تتلقى رسالة بريد إلكتروني للتحقق أو إشعار إعادة تعيين كلمة المرور ما لم تستخدم عنوان @ mailinator.com ، والتحقق مطلوب لإجراء أي تعديلات يدوية على سجلات آلية تحديد الوصول. تعرف على المزيد حول استخدام صناديق البريد الوارد العامة مجانًا هنا. إذا كنت لا ترغب في استخدام ملف Mailinator العنوان ، ثم يرجى تدوين اسم المستخدم وكلمة المرور (حيث ستستخدمهما لمنح الإذن لتطبيقك عند الاختبار) ، والاتصال بنا لطلب المساعدة في التحقق.

Mailinator هي خدمة بريد إلكتروني بها خدمة عامة مجانية وخدمة خاصة مدفوعة. للاختبار ، يمكنك استخدام الخدمة العامة المجانية تمامًا. اكتشف المزيد عن طبقاتهم هنا.

Mailinator هي خدمة تابعة لجهة خارجية لا تتم إدارتها أو صيانتها بواسطة ORCID. نوصي بمراجعة كيفية عمل هذه الخدمة وقيودها قبل استخدام هذه العناوين.

يمكن لأي شخص لديه بيانات اعتماد API عامة أو عضو الحصول على ملف / read-public رمز وصول. للحصول على رمز ، يمكنك إجراء مكالمة إلى ORCID نقطة نهاية الرمز المميز لواجهة برمجة التطبيقات.

غالبًا ما يشار إلى هذه العملية باسم تدفق OAuth لبيانات اعتماد العميل ، أو OAuth المكون من خطوتين.

مثال على مكالمة للحصول على رمز وصول لقراءة البيانات العامة على sandbox - استبدل العناصر النائبة ببيانات الاعتماد الخاصة بك (تأكد من إزالة الأقواس.

URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  METHOD: POST
  DATA: 
    client_id=[Your public API client ID]
    client_secret=[Your public API secret]
    grant_type=client_credentials
    scope=/read-public

سيتم بعد ذلك إرجاع رمز وصول مشابه لما يلي. الرمز المميز الذي تم إرجاعه طويل العمر (لا تنتهي صلاحيته لمدة 20 عامًا تقريبًا) ويمكن استخدامه عدة مرات لاسترداد البيانات العامة من ORCID السجلات. 

{"access_token":"4bed1e13-7792-4129-9f07-aaf7b88ba88f","token_type":"bearer",
"refresh_token":"2d76d8d0-6fd6-426b-a017-61e0ceda0ad2","expires_in":631138518,
"scope":"/read-public","orcid":null}

ملحوظة: جميع الرموز المميزة ذات النطاق / المصادقة تحتوي الآن أيضًا على النطاق / read-public. إذا كنت تستخدم نطاق / المصادقة فقط ، فيمكنك استخدام رموز الوصول المخزنة لقراءة البيانات العامة دون الحاجة إلى الحصول مرة أخرى على رمز وصول. 

يمكن للتكاملين الذين يستخدمون واجهة برمجة تطبيقات الأعضاء استخدام / read-public نطاق للقراءة ORCID سجل ملخصات.

للحصول على / وصول محدود للقراءة ، يجب أن تطلب الإذن من الباحث. يمكنك القيام بذلك باستخدام OAuth. خاصة، "3 أرجل بروتوكول OAuth".

لمزيد من المعلومات يرجى الاطلاع على دروس API: قراءة البيانات على ملف ORCID سجل

ORCID تستخدم عمليات الدمج "بروتوكول OAuth الثلاثي" لمصادقة المستخدمين وطلب إذن للتفاعل مع سجلاتهم. يمكن أن يطلب أي تكامل أذونات القراءة باستخدام واجهة برمجة التطبيقات العامة. ORCID يمكن للأعضاء استخدام Member API لطلب أذونات التحديث. يعمل مثل هذا:

• تقوم بإنشاء ارتباط خاص
• عند النقر فوقها ، يتم إرسال المستخدم إلى ORCID
  • ORCID يطلب من المستخدم تسجيل الدخول
  • ORCID يطلب من المستخدم منح الإذن لتطبيقك
  • ORCID يرسل المستخدم مرة أخرى إلى نظامك برمز التفويض
• يتبادل نظامك هذا الرمز للحصول على رمز وصول

يتضمن عنوان URL المخصص للمصادقة معلومات العميل ، بالإضافة إلى "النطاقات" التي تحدد مناطق معينة من سجلها التي ترغب في الوصول إليها. بعد تسجيل الدخول ، يصرح المستخدم بالاتصال بنظامك ويعود إلى صفحتك المقصودة مع رمز التفويض. ثم يتم استخدام هذا الرمز للحصول على ORCID iD جنبًا إلى جنب مع رمز وصول صالح للنطاقات المطلوبة.

بناء رابط التفويض والحصول على رمز التفويض

يمكنك إنشاء رابط التفويض الخاص بك عن طريق تحديد معرف العميل الخاص ببيانات اعتماد واجهة برمجة التطبيقات الخاصة بك وصفحة الوصول المرتبطة (URI لإعادة التوجيه). يمكنك اختيار الأذونات التي تريد طلبها عن طريق ضبط معلمة النطاق.

يطلب المثال أدناه الإذن بقراءة بيانات الوصول المحدود على ORCID خادم اختبار وضع الحماية. في العالم الحقيقي ، تقوم بعرض هذا الارتباط على موقع الويب الخاص بك ، أو تضمينه في رسالة بريد إلكتروني عندما تطلب من المستخدم المصادقة والتفويض. ومع ذلك ، لأغراض الاختبار ، يمكنك ببساطة لصقها في متصفح الويب الخاص بك. استبدل البيانات الموضوعة بين قوسين بمعلومات العميل وتأكد من إزالة الأقواس المربعة!

https://sandbox.orcid.org/oauth/authorize?client_id=[Your client ID]&response_type=code&scope=/read-limited&redirect_uri=[Your landing page]

قام المستخدم بالنقر فوق الارتباط ، وقم بتسجيل الدخول في ORCID ومنحهم أذونات ، تمت إعادة توجيههم مرة أخرى إلى موقعك ، على النحو التالي:

https://[Your landing page]?code=Q70Y3A

استبدل رمز التفويض بملف ORCID iD ورمز الوصول

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

 URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  HEADER: Content-Type: application/x-www-form-urlencoded
  METHOD: POST
  DATA: 
    client_id=[Your client ID]
    client_secret=[Your client secret]
    grant_type=authorization_code
    code=Six-digit code
    redirect_uri=[Your landing page]

ORCID سيعيد الباحث بعد ذلك مصدقًا عليه ORCID iD ورمز وصول بتنسيق JSON:

{"access_token":"f5af9f51-07e6-4332-8f1a-c0c11c1e3728","token_type":"bearer",
"refresh_token":"f725f747-3a65-49f6-a231-3e8944ce464d","expires_in":631138518,
"scope":"/read-limited","name":"Sofia Garcia","orcid":"0000-0001-2345-6789"}

تدوم رموز الوصول لفترة طويلة افتراضيًا وتنتهي بعد 20 عامًا من الإصدار. يمكن استخدام الرمز المميز عدة مرات قبل انتهاء صلاحيته.

استخدم رمز الوصول

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

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

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

يسترد هذا الاستدعاء المثال ملخصًا لملف ORCID سجل بتنسيق XML باستخدام عضو API على خادم وضع الحماية. أنت بحاجة إلى رمز وصول لتقديم طلبات API إلى Public أو Member API.

Method: GET Accept: application/vnd.orcid+xml
Authorization type and Access token: 
Bearer [Stored access token]
URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/record

ستعيد واجهة برمجة التطبيقات (API) رسالة 200 OK ، تشير إلى أن الطلب قد تم استلامه بنجاح ، والملخص الكامل لـ ORCID سجل ، بما في ذلك ملخصات العناصر الفردية.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <record:record path="/0000-0001-2345-6789" xmlns:internal="https://www.orcid.org/ns/internal" [...]>
     <funding:funding-summary put-code="4413" path="/0000-0001-2345-6789/funding/4413" visibility="public" display-index="0">
  [...] 
  </record:record>

كل عنصر (عمل ، تمويل ، توظيف ، إلخ) له أ ضع الكود. يمكن استخدام هذا للحصول على التفاصيل الكاملة للعنصر إذا لزم الأمر.

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

فيما يلي جدول بأقسام الملخص التي يمكنك استخدام واجهة برمجة التطبيقات لقراءتها.

جميع العناصر (باستثناء نص السيرة الذاتية) في ملف ORCID سجل لها ضع الكود:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>   
<record:record path="/0000-0001-2345-6789" xmlns:internal="https://www.orcid.org/ns/internal" [...]>      
<funding:funding-summary put-code="4413" path="/0000-0001-2345-6789/funding/4413" visibility="public" display-index="0">   [...] 
</record:record>

يمكن استخدام رمز الوضع هذا لإجراء مكالمة إلى API لاسترداد البيانات الكاملة لعنصر ما. يمكن الاستعلام عن العناصر التالية باستخدام ملف ضع الكود:

باستخدام نقطة نهاية القسم ووضع الكود ، يمكنك استدعاء API باستخدام رمز الوصول نفسه للحصول على هذا العنصر المحدد بالكامل. يسترد هذا المثال الاستدعاء عنصر التمويل الكامل 4413 بتنسيق XML باستخدام واجهة برمجة التطبيقات (API) للعضو على خادم آلية تحديد الصلاحيات.

Method: GET Accept: application/vnd.orcid+xml Authorization type and Access token: Bearer [stored access token]URI: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/funding/4413

مثال على مكالمة: GitHub

ستعيد واجهة برمجة التطبيقات (API) رسالة 200 موافق للإشارة إلى استلام الرسالة بنجاح وإرجاع XML الكامل لعنصر التمويل:

<?xml version="1.0"  encoding="UTF-8" standalone="yes"?>
    <funding:funding put-code="4413" path="/0000-0002-9227-8514/funding/4413" visibility="public"  [...] >
    [...] 
    </funding:funding>

يمكنك التحقق من مصدر عنصر عند قراءته إذا كنت تريد معرفة من أضافه.

معقم هواء PYRAMID : ORCID يتم تجميعها معًا بناءً على كل من معرفاتهم وعلاقة تلك المعرفات بالعمل. هناك أربعة أنواع من العلاقات:

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

توفر واجهة برمجة التطبيقات (API) الخاصة بنا الدعم لذلك في XSD. يحتوي كل عنصر على سمة فهرس العرض التي تشير إلى رتبته ضمن مجموعته. أعلى مؤشر عرض هو العنصر المفضل الذي اختاره الباحث. العناصر المضافة عبر واجهة برمجة التطبيقات (API) والتي لم يتم ترتيبها بواسطة الباحث لها فهرس عرض بقيمة 1 ويتم استخدامها كمصدر مفضل افتراضي داخل المجموعة حتى يتم تغييرها بواسطة الباحث. يحدد مؤشر العرض أيضًا ترتيب العمل عند قراءة ORCID سجل مع API.

لمزيد من المعلومات حول التجميع على ORCID السجلات ، يرجى الاطلاع على المادة دعم.

تشير ORCID التسجيل يدعم "التفاوض على المحتوى". هذا يعني أن الآلات والأنظمة الأخرى يمكن أن تسأل ORCID التسجيل لبيانات التعريف الشخصية بتنسيقات مختلفة.

أحد هذه التنسيقات هو JSON-LD ، والذي يستخدم تنسيق schema.org المفردات ، على وجه التحديد نوع الشخص، التي نربطها بالأعمال والمنظمات والمعرفات الأخرى. ندعم أيضًا XML و JSON و RDF XML و turtle ، وقمنا بتنفيذ مشاركة الموارد عبر الأصل (CORS) لتسهيل الوصول إلى بياناتنا.

• نرى هذا مشاركة مدونة للحصول على نظرة عامة على ORCID و schema.org
• ترى لدينا الوثائق الفنية على المحتوى التفاوضي

البحث عن مستخدم باستخدام cURL مثل:

curl -iL https://orcid.org/0000-0000-0000-0000

سيعود 200 حتى لو كان المستخدم لا يوجد. لتجنب ذلك ، استخدم التفاوض على المحتوى في مكالمتك مثل:

curl -iL -H 'Accept: application/xml' https://orcid.org/0000-0000-0000-0000