my_john_deere_api
1.0.0
ไคลเอนต์นี้อนุญาตให้คุณเชื่อมต่อ MyJohnDeere API โดยไม่ต้องเขียนโค้ดกระบวนการ oAuth, คำขอ API และการแบ่งหน้าของคุณเอง
get , create , put และ delete เพื่อทำการเรียก API โดยตรงที่ได้รับการรับรองความถูกต้องและง่ายดายeach , map ฯลฯ จะดึงข้อมูลหน้าใหม่ตามต้องการ เรามีเอกสาร RDoc ให้ แต่นี่คือคำแนะนำที่เป็นประโยชน์สำหรับการเริ่มต้นใช้งาน เนื่องจากชื่ออัญมณีนั้นยาว ตัวอย่างทั้งหมดจึงถือว่าทางลัดนี้:
JD = MyJohnDeereApiเพื่อว่าเมื่อท่านเห็น:
JD :: Authorizeมันหมายถึง:
MyJohnDeereApi :: Authorize ห้องสมุดนี้มีให้เหมือนอัญมณี หากต้องการใช้งาน เพียงติดตั้งอัญมณี:
gem install my_john_deere_apiหากคุณใช้ Bundler (แล้วทำไมไม่ใช้ล่ะ) ให้เพิ่ม gem ลงใน gemfile ของคุณ:
gem 'my_john_deere_api'และเรียกใช้:
bundle installนี่เป็นเส้นทางที่ง่ายที่สุดในการให้สิทธิ์ แม้ว่าผู้ใช้ของคุณจะต้องผ่านขั้นตอนเพิ่มเติมในการให้รหัสยืนยันแก่คุณ:
# 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 )ในเว็บแอป คุณต้องการให้ผู้ใช้ไม่ต้องคัดลอก/วางรหัสยืนยัน ดังนั้นคุณสามารถส่งผ่าน :oauth_callback url เมื่อผู้ใช้ให้สิทธิ์แอปของคุณกับ 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 ] ) หลังจากการอนุญาตเสร็จสมบูรณ์ ออบเจ็กต์ 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 ฯลฯ จากนั้นจึงดึงข้อมูลหน้าใหม่ตามต้องการ
ลูกค้ารายนี้เป็นงานระหว่างดำเนินการ ขณะนี้คุณสามารถทำสิ่งต่อไปนี้โดยไม่ต้องใช้การเรียก API:
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 แล้ว คอลเลกชันผลิตภัณฑ์สนับสนุนยังรองรับวิธีการต่อไปนี้:
ผลิตภัณฑ์การสนับสนุนแต่ละรายการสนับสนุนวิธีการและการเชื่อมโยงต่อไปนี้:
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_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 บังคับให้โหลดคอลเลกชันทั้งหมดจาก API ของ John Deere ดังนั้นโปรดใช้ด้วยความระมัดระวัง ไม่สามารถสร้างองค์กรผ่าน API ได้ ดังนั้นจึงไม่มีวิธี 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จัดการทรัพย์สินขององค์กร การรวบรวมสินทรัพย์รองรับวิธีการต่อไปนี้:
เนื้อหาแต่ละรายการรองรับวิธีการและการเชื่อมโยงต่อไปนี้:
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จัดการตำแหน่งของสินทรัพย์ คอลเลกชันตำแหน่งสินทรัพย์รองรับวิธีการต่อไปนี้:
สถานที่แต่ละแห่งรองรับวิธีการต่อไปนี้:
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 อย่างไรก็ตาม จะไม่มีข้อมูลใหม่เนื่องจากไม่มีการสร้าง ID เฉพาะ การประทับเวลาที่ส่ง (ซึ่งมีค่าเริ่มต้นเป็น "ตอนนี้") จะถูกปัดเศษเป็นวินาทีที่ใกล้ที่สุด
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 เพื่อความกระชับ
จัดการสาขาขององค์กร คอลเลกชันฟิลด์รองรับวิธีการต่อไปนี้:
แต่ละฟิลด์รองรับวิธีการและการเชื่อมโยงต่อไปนี้:
วิธี count ต้องโหลดหน้าแรกของผลลัพธ์เท่านั้น จึงเป็นการโทรที่ค่อนข้างถูก ในทางกลับกัน all บังคับให้โหลดคอลเลกชันทั้งหมดจาก API ของ 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 ไม่ได้จัดเตรียมจุดสิ้นสุดเพื่อดึงข้อมูลแฟล็กเฉพาะตาม id:
แต่ละแฟล็กรองรับวิธีการและการเชื่อมโยงต่อไปนี้:
วิธี count ต้องโหลดหน้าแรกของผลลัพธ์เท่านั้น จึงเป็นการโทรที่ค่อนข้างถูก ในทางกลับกัน all บังคับให้โหลดคอลเลกชันทั้งหมดจาก API ของ 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 แบบเต็ม
คำขอ DELETE ต้องการเพียงเส้นทางทรัพยากรเท่านั้น
client . delete ( '/assets/123123' )การตอบสนองมาตรฐานของ John Deere คือรหัสสถานะ HTTP 204 พร้อมข้อความ "ไม่มีเนื้อหา" วิธีการนี้ส่งคืนการตอบสนอง Net::HTTP แบบเต็ม
ข้อผิดพลาดแบบกำหนดเองช่วยระบุปัญหาได้อย่างชัดเจนเมื่อใช้ไคลเอนต์:
:sandbox หรือ :productionติดดาว อัญมณีนี้บน GitHub ช่วยให้นักพัฒนาสามารถค้นหาและเลือกอัญมณีนี้เหนืออัญมณีอื่น ๆ ที่อาจอยู่ที่นั่น ตามความรู้ของเรา ไม่มีอัญมณีอื่นๆ ของ John Deere ที่ได้รับการบำรุงรักษาอย่างจริงจัง
วิธีที่ง่ายที่สุดในการบริจาคคือ:
vcr_setupvcr_setup ด้วย
