my_john_deere_api

عميل روبي لواجهة برمجة تطبيقات MyJohnDeere

يتيح لك هذا العميل توصيل MyJohnDeere API دون الحاجة إلى ترميز عملية oAuth وطلبات API وترقيم الصفحات الخاصة بك.

• يعمل مع ريلز، لكنه لا يتطلب ذلك
• يدعم كلاً من وضع الحماية والوضع المباشر
• يبسط عملية التفاوض بشأن oAuth
• يوفر واجهة بنمط ActiveRecord للعديد من نقاط النهاية
• يوفر أساليب get create put delete لإجراء مكالمات API سهلة وموثقة ومباشرة
• يستخدم أرقام روبي للتعامل مع ترقيم الصفحات خلف الكواليس. ستجلب المكالمات مثل each map وما إلى ذلك صفحات جديدة من البيانات حسب الحاجة.

جدول المحتويات

• كيفية قراءة هذه الوثائق
• تثبيت
• التفويض مع John Deere عبر oAuth 1.0
• التفاعل مع حساب John Deere الخاص بالمستخدم
• استخدام العميل للقيام بالأشياء
  • منتجات المساهمة
  • تعريفات المساهمة
  • المنظمات
  • أصول
  • مواقع الأصول
  • الحقول
• طلبات واجهة برمجة التطبيقات المباشرة
  • يحصل
  • بريد
  • يضع
  • يمسح
• أخطاء
• كيف يمكنني المساعدة؟
  • أعطنا نجمة!
  • ساهم في هذه الجوهرة

كيفية قراءة هذه الوثائق

نحن نقدم وثائق RDoc، ولكن هنا دليل مفيد للبدء. نظرًا لأن اسم الجوهرة طويل، فستفترض جميع الأمثلة هذا الاختصار:

 JD = MyJohnDeereApi

بحيث عندما ترى:

 JD :: Authorize

يعني حقا:

 MyJohnDeereApi :: Authorize 

تثبيت

هذه المكتبة متاحة كجوهرة. لاستخدامها، فقط قم بتثبيت الجوهرة:

gem install my_john_deere_api

إذا كنت تستخدم Bundler (ولماذا لا تستخدمه؟) فقم بإضافة الجوهرة إلى ملف Gemfile الخاص بك:

 gem 'my_john_deere_api'

وتشغيل:

bundle install

التفويض مع John Deere عبر oAuth 1.0

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

 # Create an authorize object, using your app's API key and secret. You can
# pass an environment (`:live` or `:sandbox`), which default to `:live`.
authorize = JD :: Authorize . new ( API_KEY , API_SECRET , environment : :sandbox )

# Retrieve a valid authorization url from John Deere, where you can send 
# your user for authorizing your app to the JD platform.
url = authorize . authorize_url

# Verify the code given to the user during the authorization process, and
# turn this into access credentials for your user.
authorize . verify ( code )

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

 # Create an authorize object, using your app's API key and secret.
authorize = JD :: Authorize . new ( API_KEY , API_SECRET , environment : :sandbox )

# Retrieve a valid authorization url from John Deere.
url = authorize . authorize_url

# Queue elevator music while your app serves other users...

# Re-create the authorize instance in a different process
authorize = JD :: Authorize . new ( API_KEY , API_SECRET , environment : :sandbox )

# Proceed as normal
authorize . verify ( code )

في تطبيق الويب، تفضل ألا يضطر المستخدم إلى نسخ/لصق رموز التحقق. حتى تتمكن من تمرير عنوان URL :oauth_callback. عندما يقوم المستخدم بتفويض تطبيقك مع John Deere، تتم إعادة توجيهه إلى عنوان URL الذي تقدمه، باستخدام المعلمة "oauth_verifier" التي تحتوي على رمز التحقق حتى لا يضطر المستخدم إلى تقديمه.

 # Create an authorize object, using your app's API key and secret.
authorize = JD :: Authorize . new (
  API_KEY ,
  API_SECRET ,
  environment : :sandbox ,
  oauth_callback : 'https://example.com'
)

# Retrieve a valid authorization url from John Deere.
# This will contain the callback url encoded into the
# query string for you.
url = authorize . authorize_url

# Queue elevator music while your app serves other users...

# Re-create the authorize instance in a different process.
# It's not necessary to re-initialize with the callback url.
authorize = JD :: Authorize . new ( API_KEY , API_SECRET , environment : :sandbox )

# Inside a Rails controller, you might do this:
authorize . verify ( params [ :oauth_verifier ] ) 

التفاعل مع حساب John Deere الخاص بالمستخدم

بعد اكتمال الترخيص، سيوفر كائن Client معظم الواجهة لهذه المكتبة. يمكن استخدام العميل مع أو بدون بيانات اعتماد المستخدم، لأن بعض استدعاءات واجهة برمجة التطبيقات (API) خاصة بعلاقة تطبيقك مع John Deere، وليس علاقة المستخدم الخاص بك. لكن معظم التفاعلات ستتضمن بيانات المستخدم. إليك كيفية إنشاء مثيل للعميل:

 client = JD :: Client . new (
  # the application's API key
  API_KEY ,

  # the application's API secret
  API_SECRET ,

  # the chosen environment (:sandbox or :live)
  environment : :sandbox ,

  # optional contribution_definition_id. This is needed for some requests,
  # but the client can be created without it, in order to find it.
  contribution_definition_id : CONTRIBUTION_DEFINITION_ID ,

  # the user's access credentials
  access : [ ACCESS_TOKEN , ACCESS_SECRET ]
) 

استخدام العميل للقيام بالأشياء

بمجرد الاتصال، يعمل العميل كإصدار مبسط من ActiveRecord. يتم تحويل تجزئة JSON من واجهة برمجة التطبيقات (API) إلى كائنات لتسهيل التعامل معها. مجموعات من الأشياء، مثل المؤسسات، تتعامل مع ترقيم الصفحات نيابةً عنك. ما عليك سوى التكرار باستخدام each map وما إلى ذلك، وسيتم جلب الصفحات الجديدة حسب الحاجة.

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

 client
├── contribution_products
|   ├── count
|   ├── all
|   ├── first
|   └── find(contribution_product_id)
|       └── contribution_definitions
|           ├── count
|           ├── all
|           ├── first
|           └── find(contribution_definition_id)
└── organizations
    ├── count
    ├── all
    ├── first
    └── find(organization_id)
        ├── assets(attributes)
        |   ├── create(attributes)
        |   ├── count
        |   ├── all
        |   ├── first
        |   └── find(asset_id)
        |       ├── save
        |       ├── update(attributes)
        |       └── locations
        |           ├── create(attributes)
        |           ├── count
        |           ├── all
        |           └── first
        └── fields
            ├── count
            ├── all
            ├── first
            └── find(field_id)
                └── flags
                    ├── count
                    ├── all
                    └── first

منتجات المساهمة

تعمل مجموعات منتجات المساهمة كقائمة. بالإضافة إلى جميع الطرق المضمنة عبر وحدة Ruby's Enumerable، تدعم مجموعات المنتجات المساهمة الطرق التالية:

• الجميع
• عدد
• أولاً
• العثور على (مساهمة_منتج_id)

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

• بطاقة تعريف
• اسم_مكان_السوق
• Market_place_description
• default_locale
• current_status
• activation_callback
• Preview_images
• support_regions
• مراكز_العمليات المدعومة
• الروابط
• تعريفات_المساهمة (مجموعة تعريفات مساهمة منتج المساهمة هذا)

 client . contribution_products
# => collection of contribution products under this client

client . contribution_products . count
# => 1

client . contribution_products . first
# => an individual contribution product

contribution_product = client . contribution_products . find ( 1234 )
# => an individual contribution product, fetched by ID

contribution_product . market_place_name
# => 'Market Place Name'

contribution_product . contribution_definitions
# => collection of contribution definitions belonging to this contribution product

تعريفات المساهمة

يعالج تعريفات مساهمة منتج المساهمة. تدعم مجموعات تعريف المساهمة الطرق التالية:

• الجميع
• عدد
• أولاً
• العثور على (contribution_definition_id)

يدعم تعريف المساهمة الفردية الطرق والجمعيات التالية:

• بطاقة تعريف
• اسم
• الروابط

 contribution_product . contribution_definitions
# => collection of contribution definitions under this contribution product

client . contribution_definitions . count
# => 1

client . contribution_definitions . first
# => an individual contribution definition

contribution_definition = contribution_product . contribution_definitions . find ( 1234 )
# => an individual contribution definition, fetched by ID

contribution_definition . name
# => 'Contribution Definition Name'

المنظمات

يتعامل مع منظمات الحساب. تدعم مجموعات المؤسسة الطرق التالية:

• الجميع
• عدد
• أولاً
• العثور على (معرف_المنظمة)

تدعم منظمة فردية الأساليب والجمعيات التالية:

• بطاقة تعريف
• اسم
• يكتب
• عضو؟
• الروابط
• الأصول (مجموعة أصول هذه المنظمة)
• الحقول (مجموعة حقول هذه المنظمة)

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

 client . organizations
# => collection of organizations under this client

client . organizations . count
# => 15

client . organizations . first
# => an individual organization object

organization = client . organizations . find ( 1234 )
# => an individual organization object, fetched by ID

organization . name
# => 'Smith Farms'

organization . type
# => 'customer'

organization . member?
# => true

organization . links
# =>  {
#       'self' => 'https://sandboxapi.deere.com/platform/organizations/1234',
#       'machines' => 'https://sandboxapi.deere.com/platform/organizations/1234/machines',
#       'wdtCapableMachines' => 'https://sandboxapi.deere.com/platform/organizations/1234/machines?capability=wdt'   
#     }

organization . assets
# => collection of assets belonging to this organization

organization . fields
# => collection of fields belonging to this organization

أصول

يتعامل مع أصول المنظمة. تدعم مجموعات الأصول الطرق التالية:

• إنشاء (سمات)
• الجميع
• عدد
• أولاً
• العثور على (asset_id)

يدعم الأصل الفردي الطرق والارتباطات التالية:

• بطاقة تعريف
• عنوان
• فئة
• يكتب
• sub_type
• الروابط
• تحديث (السمات)
• المواقع (مجموعة مواقع هذا الأصل)

 organization = client . organizations . first
# => the first organization returned by the client

organization . assets
# => collection of assets belonging to this organization

asset = organization . assets . find ( 123 )
# => an individual asset object, fetched by ID

asset . title
# => 'AgThing Water Device'

asset . category
# => 'DEVICE'

asset . type
# => 'SENSOR'

asset . sub_type
# => 'OTHER'

asset . links
# => a hash of API urls related to this asset

تقوم طريقة create بإنشاء الأصل في نظام John Deere الأساسي، وإرجاع السجل الذي تم إنشاؤه حديثًا.

 asset = organization . assets . create (
  title : 'Asset Title' ,
  asset_category : 'DEVICE' ,
  asset_type : 'SENSOR' ,
  asset_sub_type : 'ENVIRONMENTAL'
)

asset . title
# => 'Asset Title'

تقوم طريقة update بتحديث الكائن المحلي، وكذلك الأصل الموجود على النظام الأساسي John Deere. يمكن تحديث عنوان الأصل فقط.

 asset . update ( title : 'New Title' )
asset . title
# => 'New Title', also John Deere record is updated

تقوم طريقة save بتحديث John Deere بأية تغييرات محلية تم إجراؤها.

 asset . title = 'New Title'
asset . save
# => Successful Net::HTTPNoContent object

مواقع الأصول

يعالج مواقع الأصول. تدعم مجموعات مواقع الأصول الطرق التالية:

• إنشاء (سمات)
• الجميع
• عدد
• أولاً

يدعم الموقع الفردي الطرق التالية:

• الطابع الزمني
• هندسة
• Measure_data

 asset = organizations . assets . first
# => the first asset returned by the organization

asset . locations
# => collection of locations belonging to this asset

location = asset . locations . first
# => the first location returned by the asset. Note that locations do not have their own id's
#    in the JD platform, and therefore cannot be requested individually via a "find" method.

location . timestamp
# => "2019-11-11T23:00:00.000Z"
#    John Deere includes 3 decimal places in the format, but does not actually
#    store fractions of a second, so it will always end in ".000". This is
#    important, because timestamps must be unique.

location . geometry
# =>  a GeoJSON formatted hash, for example:
#     {
#       "type"=>"Feature",
#       "geometry"=>{
#         "geometries"=>[
#             {
#               "coordinates"=>[-95.123456, 40.123456], 
#               "type"=>"Point"
#             }
#           ],
#         "type"=>"GeometryCollection"
#       }
#     }

location . measurement_data
# =>  the status details of this location, for example:
#     [
#       {
#         "@type"=>"BasicMeasurement",
#         "name"=>"[Soil Temperature](http://example.com/current_temperature)", 
#         "value"=>"21.0", 
#         "unit"=>"°C"
#       }
#     ]

تقوم طريقة create بإنشاء الموقع في نظام John Deere الأساسي، وإرجاع الكائن المنشأ حديثًا من John Deere. ومع ذلك، لن تكون هناك معلومات جديدة نظرًا لعدم إنشاء معرف فريد. سيتم تقريب الطابع الزمني الذي تم إرساله (والذي الافتراضي هو "الآن") إلى أقرب ثانية.

 locaton = asset . locatons . create (
  # You can pass fractional seconds, but they will be truncated by JD.
  timestamp : "2019-11-11T23:00:00.123Z" ,

  # JD requires more complicated JSON geometry, but this client will convert a simple
  # set of lat/long coordinates into the larger format automatically.
  geometry : [ - 95.123456 , 40.123456 ] ,

  # This is a list of "measurements"
  measurement_data : [
    {
      name : 'Temperature' ,
      value : '68.0' ,
      unit : 'F'
    }
  ]
)

location . timestamp
# =>  "2019-11-11T23:00:00.000Z"
#     Note that the timestamp's fractional second is truncated by John Deere, though they
#     still return the record with three digits of precision.

location . geometry
# =>  a GeoJSON formatted hash in its larger format
#     {
#       "type"=>"Feature",
#       "geometry"=>{
#         "geometries"=>[
#             {
#               "coordinates"=>[-95.123456, 40.123456], 
#               "type"=>"Point"
#             }
#           ],
#         "type"=>"GeometryCollection"
#       }
#     }

location . measurement_data
#     [
#       {
#         "@type"=>"BasicMeasurement",
#         "name"=>"Temperature", 
#         "value"=>"68.0", 
#         "unit"=>"F"
#       }
#     ]

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

لاحظ أن المواقع تسمى "مواقع الأصول" في John Deere، ولكننا نسمي الارتباط "مواقع"، كما في asset.locations ، للإيجاز.

الحقول

يتعامل مع حقول المنظمة. تدعم المجموعات الميدانية الطرق التالية:

• الجميع
• عدد
• أولاً
• العثور على (field_id)

يدعم الحقل الفردي الأساليب والارتباطات التالية:

• بطاقة تعريف
• اسم
• المؤرشفة؟
• الروابط
• الأعلام (مجموعة من أعلام هذا المجال)

تتطلب طريقة count فقط تحميل الصفحة الأولى من النتائج، لذا فهي طريقة رخيصة نسبيًا. من ناحية أخرى، all يفرض تحميل المجموعة بأكملها من واجهة برمجة تطبيقات John Deere، لذا استخدمها بحذر. يمكن إنشاء الحقول عبر واجهة برمجة التطبيقات (API)، ولكن لا توجد طريقة create في هذه المجموعة حتى الآن.

 organization . fields
# => collection of fields under this organization

organization . fields . count
# => 15

organization . fields . first
# => an individual field object

field = organization . fields . find ( 1234 )
# => an individual field object, fetched by ID

field . name
# => 'Smith Field'

field . archived?
# => false

field . links
# => a hash of API urls related to this field

field . flags
# => collection of flags belonging to this field

أعلام

يتعامل مع أعلام الميدان. تدعم مجموعات العلامات الطرق التالية. لاحظ أن John Deere لا يوفر نقطة نهاية لاسترداد علامة محددة حسب المعرف:

• الجميع
• عدد
• أولاً

تدعم العلامة الفردية الطرق والارتباطات التالية:

• بطاقة تعريف
• ملحوظات
• هندسة
• المؤرشفة؟
• هل تم تمكين القرب؟
• الروابط

تتطلب طريقة count فقط تحميل الصفحة الأولى من النتائج، لذا فهي طريقة رخيصة نسبيًا. من ناحية أخرى، all يفرض تحميل المجموعة بأكملها من واجهة برمجة تطبيقات John Deere، لذا استخدمها بحذر. يمكن إنشاء العلامات عبر واجهة برمجة التطبيقات (API)، ولكن لا توجد طريقة create في هذه المجموعة حتى الآن.

 field . flags
# => collection of flags under this field

field . flags . count
# => 15

flag = field . flags . first
# => an individual flag object

flag . notes
# => 'A big rock on the left after entering the field'

flag . geometry
# =>  a GeoJSON formatted hash, for example:
#     {
#       "type"=>"Feature",
#       "geometry"=>{
#         "geometries"=>[
#             {
#               "coordinates"=>[-95.123456, 40.123456], 
#               "type"=>"Point"
#             }
#           ],
#         "type"=>"GeometryCollection"
#       }
#     }


field . archived?
# => false

field . proximity_alert_enabled?
# => true

field . links
# => a hash of API urls related to this flag 

طلبات واجهة برمجة التطبيقات المباشرة

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

يحصل

تتطلب طلبات GET مسار المورد فقط.

 client . get ( '/organizations' )

استجابة العينة المختصرة:

{
  "links" : [ " ... " ],
  "total" : 1 ,
  "values" : [
    {
      "@type" : " Organization " ,
      "name" : " ABC Farms " ,
      "type" : " customer " ,
      "member" : true ,
      "id" : " 123123 " ,
      "links" : [ " ... " ]
    }
  ]
}

لن يوفر هذا أي ميزات للعميل مثل ترقيم الصفحات أو التحقق من الصحة، ولكنه يقوم بتحليل JSON الذي تم إرجاعه.

بريد

تتطلب طلبات POST مسارًا للمورد وتجزئة لنص الطلب. سيقوم العميل بتجميع المفاتيح وتحويلها إلى JSON.

 client . post (
 '/organizations/123123/assets' ,
 {
   "title" => "i like turtles" ,
   "assetCategory" => "DEVICE" ,
   "assetType" => "SENSOR" ,
   "assetSubType" => "ENVIRONMENTAL" ,
   "links" => [
     {
       "@type" => "Link" ,
       "rel" => "contributionDefinition" ,
       "uri" => "https://sandboxapi.deere.com/platform/contributionDefinitions/CONTRIBUTION_DEFINITION_ID"
     }
    ]
  }
)

الاستجابة القياسية لـ John Deere هي رمز حالة HTTP 201، مع الرسالة "تم الإنشاء". تقوم هذه الطريقة بإرجاع استجابة Net::HTTP الكاملة.

يضع

تتطلب طلبات PUT مسارًا للمورد وتجزئة لنص الطلب. سيقوم العميل بتجميع المفاتيح وتحويلها إلى JSON.

 client . put (
 '/assets/123123' ,
 {
   "title" => "i REALLY like turtles" ,
   "assetCategory" => "DEVICE" ,
   "assetType" => "SENSOR" ,
   "assetSubType" => "ENVIRONMENTAL" ,
   "links" => [
     {
       "@type" => "Link" ,
       "rel" => "contributionDefinition" ,
       "uri" => "https://sandboxapi.deere.com/platform/contributionDefinitions/CONTRIBUTION_DEFINITION_ID"
     }
    ]
  }
)

الاستجابة القياسية لـ John Deere هي رمز حالة HTTP 204، مع الرسالة "لا يوجد محتوى". تقوم هذه الطريقة بإرجاع استجابة Net::HTTP الكاملة.

يمسح

تتطلب طلبات الحذف مسار المورد فقط.

 client . delete ( '/assets/123123' )

الاستجابة القياسية لـ John Deere هي رمز حالة HTTP 204، مع الرسالة "لا يوجد محتوى". تقوم هذه الطريقة بإرجاع استجابة Net::HTTP الكاملة.

أخطاء

تساعد الأخطاء المخصصة في تحديد المشكلات بوضوح عند استخدام العميل:

• يظهر خطأ UnsupportedEnvironmentError عند محاولة إنشاء مثيل لعميل في بيئة غير معروفة. البيئات الصالحة هي :sandbox أو :production .
• يتم ظهور خطأ InvalidRecordError عند تقديم مدخلات سيئة، في محاولة لإنشاء سجل أو تحديثه على نظام John Deere الأساسي.
• يتم ظهور MissingContributionDefinitionIdError عندما لا يتم تعيين مساهمة_definition_id الاختيارية في العميل، ولكن تمت محاولة إجراء عملية تتطلب ذلك - مثل إنشاء أصل في منصة John Deere.
• يُطلق الدالة TypeMismatchError عند إنشاء نموذج، عادةً عند استلام سجل من John Deere وتحويله إلى كائن Ruby. تتم معالجة إنشاء مثيل النموذج عادةً عن طريق كائنات الطلب، ولكن هذا الخطأ مفيد إذا كنت تقوم بإنشاء مثيل للنماذج الخاصة بك للاستخدام المتقدم.
• يتم ظهور NotYetImplementedError عند محاولة استخدام ميزة مخصصة للتطوير المستقبلي، ولكن لم يتم تنفيذها في هذا العميل بعد. هذه فرصة عظيمة للمساهمة في هذه الجوهرة!

كيف يمكنني المساعدة؟

أعطنا نجمة!

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

ساهم في هذه الجوهرة

أسهل طريقة للمساهمة هي:

• استنساخ الريبو
• إنشاء فرع الميزة
• Grep لـ "رفع NotYetImplementedError" في دليل lib
• استبدل أحد هذه الاستثناءات برمز العمل، مع اتباع الاتفاقيات المستخدمة في بقية التطبيق
• اختبار كل شيء!
• تشغيل الاختبارات.
  • قد تحتاج إلى إعادة إنشاء جميع أشرطة VCR من البداية.
  • يجب تسجيل جميع أشرطة VCR مسبقًا في vcr_setup
  • يجب إزالة أي شيء تم إنشاؤه في صندوق الحماية JD نتيجة لتشغيل الاختبارات، أيضًا في vcr_setup .
• عند اجتياز الاختبارات، أرسل طلب سحب.