my_john_deere_api
1.0.0
이 클라이언트를 사용하면 자체 oAuth 프로세스, API 요청 및 페이지 매김을 코딩하지 않고도 MyJohnDeere API에 연결할 수 있습니다.
get , create , put 및 delete 메소드 제공each , map 등과 같은 호출은 필요에 따라 새로운 데이터 페이지를 가져옵니다. 우리는 RDoc 문서를 제공하지만 시작하는 데 유용한 가이드는 다음과 같습니다. gem 이름이 길기 때문에 모든 예시에서는 다음과 같은 지름길을 가정합니다.
JD = MyJohnDeereApi그래서 당신이 볼 때 :
JD :: Authorize실제로 의미하는 바는 다음과 같습니다.
MyJohnDeereApi :: Authorize 이 라이브러리는 gem으로 제공됩니다. 이를 사용하려면 gem을 설치하세요.
gem install my_john_deere_apiBundler를 사용하고 있다면(왜 사용하지 않겠습니까?) gemfile에 gem을 추가하세요:
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로 앱을 인증하면 사용자가 인증 코드를 제공할 필요가 없도록 인증 코드가 포함된 'oauth_verifier' 매개변수와 함께 제공한 URL로 리디렉션됩니다.
# 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의 단순화된 버전처럼 작동합니다. API의 JSON 해시는 작업하기 더 쉽게 객체로 변환됩니다. 조직과 같은 항목의 컬렉션이 페이지 매김을 처리합니다. 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 John Deere의 API에서 전체 컬렉션을 강제로 로드하므로 주의해서 사용하세요. 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 John Deere의 API에서 전체 컬렉션을 강제로 로드하므로 주의해서 사용하세요. 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 John Deere의 API에서 전체 컬렉션을 강제로 로드하므로 주의해서 사용하세요. 플래그는 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의 표준 응답은 "Created" 메시지가 포함된 201 HTTP 상태 코드입니다. 이 메서드는 전체 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의 표준 응답은 "No Content" 메시지가 포함된 204 HTTP 상태 코드입니다. 이 메서드는 전체 Net::HTTP 응답을 반환합니다.
DELETE 요청에는 리소스 경로만 필요합니다.
client . delete ( '/assets/123123' )John Deere의 표준 응답은 "No Content" 메시지가 포함된 204 HTTP 상태 코드입니다. 이 메서드는 전체 Net::HTTP 응답을 반환합니다.
사용자 정의 오류는 클라이언트 사용 시 문제를 명확하게 식별하는 데 도움이 됩니다.
:sandbox 또는 :production 입니다.GitHub에서 이 보석에 별표를 표시하세요 . 이는 개발자가 다른 보석보다 이 보석을 찾고 선택하는 데 도움이 됩니다. 우리가 아는 바로는 적극적으로 유지관리되고 있는 다른 John Deere 보석은 없습니다.
가장 쉬운 기여 방법은 다음과 같습니다.
vcr_setup 에 사전 녹화되어 있어야 합니다.vcr_setup 에서도 제거되어야 합니다.
