my_john_deere_api
1.0.0
Klien ini memungkinkan Anda menghubungkan API MyJohnDeere tanpa harus membuat kode proses oAuth, permintaan API, dan penomoran halaman Anda sendiri.
get , create , put , dan delete untuk membuat panggilan API langsung yang mudah dan terautentikasieach , map , dll akan mengambil halaman data baru sesuai kebutuhan. Kami menyediakan dokumentasi RDoc, namun berikut adalah panduan berguna untuk memulai. Karena nama permatanya panjang, semua contoh akan menggunakan pintasan ini:
JD = MyJohnDeereApiSehingga ketika Anda melihat:
JD :: AuthorizeArtinya:
MyJohnDeereApi :: Authorize Perpustakaan ini tersedia sebagai permata. Untuk menggunakannya, cukup instal permata:
gem install my_john_deere_apiJika Anda menggunakan Bundler (dan mengapa tidak?) lalu tambahkan permata ke file permata Anda:
gem 'my_john_deere_api'dan jalankan:
bundle installIni adalah jalur paling sederhana untuk melakukan otorisasi, meskipun pengguna Anda harus melewati rintangan ekstra untuk memberi Anda kode verifikasi:
# 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 )Pada kenyataannya, Anda mungkin perlu membuat instance ulang objek otorisasi saat pengguna kembali, dan itu berfungsi tanpa masalah:
# 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 )Di aplikasi web, Anda lebih suka pengguna Anda tidak perlu menyalin/menempelkan kode verifikasi. Jadi Anda bisa memasukkan url :oauth_callback. Saat pengguna mengotorisasi aplikasi Anda dengan John Deere, mereka dialihkan ke url yang Anda berikan, dengan parameter 'oauth_verifier' yang berisi kode verifikasi sehingga pengguna tidak perlu memberikannya.
# 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 ] ) Setelah otorisasi selesai, objek Client akan menyediakan sebagian besar antarmuka untuk perpustakaan ini. Klien dapat digunakan dengan atau tanpa kredensial pengguna, karena beberapa panggilan API dikhususkan untuk hubungan aplikasi Anda dengan John Deere, bukan hubungan pengguna Anda. Namun sebagian besar interaksi akan melibatkan data pengguna. Berikut cara membuat instance klien:
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 ]
) Setelah Anda terhubung, klien bekerja seperti versi ActiveRecord yang disederhanakan. Hash JSON dari API diubah menjadi objek agar lebih mudah digunakan. Kumpulan berbagai hal, seperti organisasi, menangani penomoran halaman untuk Anda. Cukup ulangi menggunakan each , map , dll, dan halaman baru diambil sesuai kebutuhan.
Klien ini sedang dalam proses. Saat ini Anda dapat melakukan hal-hal berikut tanpa menggunakan panggilan 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
Kontribusi Koleksi Produk bertindak seperti daftar. Selain semua metode yang disertakan melalui Modul Enumerable Ruby, koleksi produk kontribusi mendukung metode berikut:
Produk kontribusi individu mendukung metode dan asosiasi berikut:
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 productMenangani definisi kontribusi produk kontribusi. Koleksi definisi kontribusi mendukung metode berikut:
Definisi kontribusi individu mendukung metode dan asosiasi berikut:
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'Menangani organisasi akun. Koleksi organisasi mendukung metode berikut:
Sebuah organisasi individu mendukung metode dan asosiasi berikut:
Metode count hanya memerlukan pemuatan halaman pertama hasil, jadi ini merupakan panggilan yang relatif murah. Di sisi lain, all memaksa seluruh koleksi dimuat dari API John Deere, jadi gunakan dengan hati-hati. Organisasi tidak dapat dibuat melalui API, jadi tidak ada metode create pada koleksi ini.
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 organizationMenangani aset organisasi. Pengumpulan aset mendukung metode berikut:
Aset individual mendukung metode dan asosiasi berikut:
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 Metode create membuat aset di platform John Deere, dan mengembalikan rekaman yang baru dibuat.
asset = organization . assets . create (
title : 'Asset Title' ,
asset_category : 'DEVICE' ,
asset_type : 'SENSOR' ,
asset_sub_type : 'ENVIRONMENTAL'
)
asset . title
# => 'Asset Title' Metode update memperbarui objek lokal, dan juga aset pada platform John Deere. Hanya judul aset yang dapat diperbarui.
asset . update ( title : 'New Title' )
asset . title
# => 'New Title', also John Deere record is updated Metode save memperbarui John Deere dengan perubahan lokal apa pun yang telah dibuat.
asset . title = 'New Title'
asset . save
# => Successful Net::HTTPNoContent objectMenangani lokasi aset. Pengumpulan Lokasi Aset mendukung metode berikut:
Lokasi individual mendukung metode berikut:
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"
# }
# ] Metode create membuat lokasi di platform John Deere, dan mengembalikan objek yang baru dibuat dari John Deere. Namun, tidak akan ada informasi baru karena tidak ada ID unik yang dihasilkan. Stempel waktu yang dikirimkan (yang defaultnya adalah "sekarang") akan dibulatkan ke detik terdekat.
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"
# }
# ]Tidak ada pembaruan atau penghapusan lokasi. Catatan lokasi terbaru selalu bertindak sebagai status aset tertentu, dan muncul pada tampilan peta.
Perhatikan bahwa lokasi disebut "Lokasi Aset" di John Deere, namun kami menyebut asosiasi tersebut "lokasi", seperti dalam asset.locations , agar singkatnya.
Menangani bidang organisasi. Koleksi lapangan mendukung metode berikut:
Bidang individual mendukung metode dan asosiasi berikut:
Metode count hanya memerlukan pemuatan halaman pertama hasil, jadi ini merupakan panggilan yang relatif murah. Di sisi lain, all memaksa seluruh koleksi dimuat dari API John Deere, jadi gunakan dengan hati-hati. Bidang dapat dibuat melalui API, namun belum ada metode create pada koleksi ini.
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 fieldMenangani bendera lapangan. Koleksi bendera mendukung metode berikut. Catatan, John Deere tidak menyediakan titik akhir untuk mengambil tanda tertentu berdasarkan id:
Bendera individual mendukung metode dan asosiasi berikut:
Metode count hanya memerlukan pemuatan halaman pertama hasil, jadi ini merupakan panggilan yang relatif murah. Di sisi lain, all memaksa seluruh koleksi dimuat dari API John Deere, jadi gunakan dengan hati-hati. Bendera dapat dibuat melalui API, namun belum ada metode create pada koleksi ini.
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 Meskipun tujuan klien adalah menghilangkan kebutuhan untuk melakukan/menafsirkan panggilan ke John Deere API, penting untuk dapat melakukan panggilan yang belum sepenuhnya didukung oleh klien. Atau terkadang, Anda perlu memecahkan masalah.
Permintaan GET hanya memerlukan jalur sumber daya.
client . get ( '/organizations' )Contoh tanggapan yang disingkat:
{
"links" : [ " ... " ],
"total" : 1 ,
"values" : [
{
"@type" : " Organization " ,
"name" : " ABC Farms " ,
"type" : " customer " ,
"member" : true ,
"id" : " 123123 " ,
"links" : [ " ... " ]
}
]
}Ini tidak akan memberikan manfaat klien apa pun seperti penomoran halaman atau validasi, tetapi ini mengurai JSON yang dikembalikan.
Permintaan POST memerlukan jalur sumber daya, dan hash untuk isi permintaan. Klien akan membuat kunci menjadi camel, dan mengonversinya ke 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"
}
]
}
)Respons standar John Deere adalah kode status HTTP 201, dengan pesan "Dibuat". Metode ini mengembalikan respons Net::HTTP secara penuh.
Permintaan PUT memerlukan jalur sumber daya, dan hash untuk isi permintaan. Klien akan membuat kunci menjadi camel, dan mengonversinya ke 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"
}
]
}
)Respons standar John Deere adalah kode status HTTP 204, dengan pesan "Tidak Ada Konten". Metode ini mengembalikan respons Net::HTTP secara penuh.
Permintaan DELETE hanya memerlukan jalur sumber daya.
client . delete ( '/assets/123123' )Respons standar John Deere adalah kode status HTTP 204, dengan pesan "Tidak Ada Konten". Metode ini mengembalikan respons Net::HTTP secara penuh.
Kesalahan khusus membantu mengidentifikasi masalah dengan jelas saat menggunakan klien:
:sandbox atau :production .Bintangi permata ini di GitHub. Ini membantu pengembang menemukan dan memilih permata ini dibandingkan permata lain yang mungkin ada di luar sana. Sepengetahuan kami, tidak ada permata John Deere lain yang dipelihara secara aktif.
Cara termudah untuk berkontribusi adalah:
vcr_setupvcr_setup .
