kintone

A Ruby gem for communicating with the kintone REST API

Requirements

• ruby 2.4.0 or later

Installation

gem install kintone-oauth-extension

or execute bundle install command after you insert the following into Gemfile

gem 'kintone-oauth-extension'

Usage

“by require ‘kintone’

Use password authentication

api = Kintone::Api.new(“example.cybozu.com”, “Administrator”, “cybozu”)

Use token authentication

api = Kintone::Api.new(“example.cybozu.com”, “authtoken”)

Use OAuth authentication

api = Kintone::OAuthApi.new(“example.cybozu.com”, “access_token”)

if set oauth options below, you can refresh the access_token.

oauth_options = { client_id: ‘client_id’, client_secret: ‘client_secret’, refresh_token: ‘refresh_token’, expires_at: 1599921045 } api = Kintone::OAuthApi.new(“example.cybozu.com”, “access_token”, oauth_options)

get new token.

api.refresh! api.access_token.token

=> “new_access_token”

“

Supported API

• Record retrieval
• Record register
• Record update
• Record delete
• Bulk request
• File
• Permissions
• Space management
• Guests
• Application information
• Form structure
• API information

Maruku could not parse this XML/HTML: 
<a name="record_retrieval"> Record retrieval

“by

Record retrieval(Assign by Record Number)

app = 8; id = 100 api.record.get(app, id) # => => {“record_id” => {“type” => “RECORD_NUMBER”, “value” => “1”}}

Records retrieval(Assign by Conditions by Query Strings)

app = 8; fields = [record_id, created_time, dropdown] query = “updated_time > "2012-02-03T09:00:00+0900" and updated_time < "2012-02-03T10:00:00+0900" order by record_id asc limit 10 offset 20” api.records.get(app, query, fields) # => => [, ]

“

Query helper

“by query = Kintone::Query.new do field(:updated_time) > “2012-02-03T09:00:00+0900” and! field(:updated_time) < “2012-02-03T10:00:00+0900” order_by(:record_id) limit(10) offset(20) end

or

query = Kintone::Query.new do f(:updated_time) > “2012-02-03T09:00:00+0900” and! f(:updated_time) < “2012-02-03T10:00:00+0900” order_by(:record_id) limit(10) offset(20) end query.to_s # => “updated_time > "2012-02-03T09:00:00+0900" and updated_time < "2012-02-03T10:00:00+0900" order by record_id asc limit 10 offset 20” api.records.get(app, query, fields)

Example

Kintone::Query.new do field(:Created_datetime) >= last_month and! precede do field(:text).like(“Hello”) and! field(:number) == 200 end or! precede do field(:number) > 100 and! field(:Created_by).in([login_user]) end order_by(:record_id, :desc) limit(10) offset(20) end

=> “Created_datetime >= LAST_MONTH() and (text like "Hello" and number = 200) or (number > 100 and Created_by in (LOGINUSER())) order by record_id desc limit 10 offset 20”

“

operator symbol	query helper
=	field(:code) == other
!=	field(:code) != other
>	field(:code) > other
<	field(:code) < other
>=	field(:code) >= other
<=	field(:code) <= other
in	field(:code).in([A, B])
not in	field(:code).not_in([A, B])
like	field(:code).like(“Hello”)
not like	field(:code).not_like(“Hello”)
and	and!
or	or!
()	precede do; end

function	query helper
LOGINUSER()	login_user
PRIMARY_ORGANIZATION()	primary_organization
NOW()	now
TODAY()	today
THIS_MONTH()	this_month
LAST_MONTH()	last_month
THIS_YEAR()	this_year

option	query helper
order by	order_by(:code, :asc or :desc)
limit	limit(20)
offset	offset(30)

Maruku could not parse this XML/HTML: 
<a name="record_register"> Record register

“by

Record register(single record)

Use Hash

app = 7 record = => {“value” => “123456”} api.record.register(app, record) # => => “100”, “revision” => “1”

Use Kintone::Type::Record

app = 7 record = Kintone::Type::Record.new(number: “123456”) api.record.register(app, record) # => => “100”, “revision” => “1”

Records register(batch)

Use Hash

app = 7 records = [=> {value => 123456}, => {value => 7890}] api.records.register(app, records) # => => [100, 101], “revisions” => [1, 1]

Use Kintone::Type::Record

app = 7 records = [Kintone::Type::Record.new(number: 123456), Kintone::Type::Record.new(number: 7890)] api.records.register(app, records) # => => [100, 101], “revisions” => [1, 1]

“

Maruku could not parse this XML/HTML: 
<a name="record_update"> Record update

“by

Record update(single record)

Use Hash

app = 4; id = 1 record = => {“value” => “changed!”} api.record.update(app, id, record) # => => “2”

Use Kintone::Type::Record

app = 4; id = 1 record = Kintone::Type::Record.new(“changed!”) api.record.update(app, id, record) # => => “2”

With revision

api.record.update(app, id, record, revision: 1)

Records update(batch)

Use Hash

app = 4 records = [=> 1, record => {string_multi => {value => abcdef}}, => 2, record => {string_multi => {value => opqrstu}}] api.records.update(app, records) # => => [{id => 1, revision => 2, => 2, revision => 2]}

Use Kintone::Type::Record

app = 4 records = [1, record: Kintone::Type::Record.new(string_multi: abcdef), 2, record: Kintone::Type::Record.new(string_multi: opqrstu)] api.records.update(app, records) # => => [{id => 1, revision => 2, => 2, revision => 2]}

with revision

records = [1, revision: 1, record: Kintone::Type::Record.new(string_multi: abcdef), 2, revision: 1, record: Kintone::Type::Record.new(string_multi: opqrstu)] api.records.update(app, records)

“

Maruku could not parse this XML/HTML: 
<a name="record_delete"> Record delete

“by app = 8; ids = [100, 80] api.records.delete(app, ids) # => {}

With revision

revisions = [1, 1] api.records.delete(app, ids, revisions: revisions)

“

Maruku could not parse this XML/HTML: 
<a name="bulk_request"> Bulk request

“by requests = [{method => POST, }, {method => PUT, }] api.bulk.request(requests) # => []

“

Maruku could not parse this XML/HTML: 
<a name="file"> File

“by

File upload

file_key = api.file.register(“/path/to/file”, “text/plain”, “file.txt”)

File download

file = api.file.get(file_key)

“

Maruku could not parse this XML/HTML: 
<a name="permissions"> Permissions

“by

App

app = 1 rights = [=> {type => USER, code => user1, appEditable => true, }, ] api.app_acl.update(app, rights) # => {}

Records

id = 1 rights = [{filterCond => , entities => {entity => , viewable => false, }, }, ] api.record_acl.update(id, rights) # => {}

Fields

id = 1 rights = [=> Single_line_text_0, entities => {entity => , accesibility => WRITE, }, ] api.field_acl.update(id, rights) # => {}

“

Maruku could not parse this XML/HTML: 
<a name="space_management"> Space management

“by

Space information

id = 1 api.space.get(id) # => { “id” => “1”, “name” => “space”, “defaultThread” => “3”, “isPrivate” => true, …}

Create space

id = 1; name = “sample space” members = [=> {type => USER, code => user1, isAdmin: true}, ] api.template_space.create(id, name, members, is_guest: true, fixed_member: false) # => => “1”

Space body update

id = 1; body = “awesome space!” api.space_body.update(id, body) # => {}

Space members

id = 1 members = api.space_members.get(id) # => code=> user1, }, ]} members « => {“type” => “GROUP”, “code” => “group1”} members = api.space_members.update(id, members) # => {}

Space thread update

id = 1; name = “thread name” body = “awesome thread!” api.space_thread.update(id, name: name, body: body) # => {}

Space guests

id = 1 guests = [hoge@example.com] api.guest(1).space_guests.update(id, guests) # => {}

Space delete

id = 1 api.space.delete(id) # => {}

“

Maruku could not parse this XML/HTML: 
<a name="guests"> Guests

“by

Add guest

guests = [{code: hoge@example.com, password: p@ssword, timezone: Asia/Tokyo, name: Tokyo, Saburo, }, ] api.guests.register(guests) # => {}

delete guest

guests = [hoge@example.com, fuga@example.com] api.guests.delete(guests) # => {}

“

Maruku could not parse this XML/HTML: 
<a name="application_information"> Application information

“by id = 4 api.app.get(id) # => => “4”, “code” => “”, …

name = “test”; codes = [FOO, BAR] api.apps.get({ name: name, codes: codes }) # => { “apps” => [, ] }

“

Maruku could not parse this XML/HTML: 
<a name="form_structure"> Form structure

“by app = 1 api.form.get(app) # => => [, ]

api.preview_form.get(app) # => => [, ]

“

Maruku could not parse this XML/HTML: 
<a name="api_information"> API information

“by api.apis.get # => => “https://example.cybozu.com/k/v1/”, “apis” => {“records/get” => {“link” => “apis/records/get.json”}}

api.apis.get_details_of(“apis/records/get.json”) # => => “GetRecords”, “baseUrl” => “https://example.cybozu.com/k/v1/”, …

api.apis.get_details_of_key(“records/get”) # => => “GetRecords”, “baseUrl” => “https://example.cybozu.com/k/v1/”, …

“

Other examples

“by

Format retrieval

url = api.get_url(“form”) api.get(url, => 4) # => => [, ]

Batch record register

url = api.get_url(“records”) body = => 7, “records” => [, ] api.post(url, body) # => => [100,101]

“

Access to guest spaces

“by api.guest(1).record.get(8, 100)

“

see also kintone developers