kintone iOS SDK

aki发表于:2019年09月13日 13:28:55更新于:2020年09月09日 14:00:10

目前已不推荐此工具!

Index

概要

本篇介绍于2019年2月发布的“kintone iOS SDK”。
有了本次发布的“kintone iOS SDK”,可更加简单方便地使用Swift或Objective-C执行kintone REST API。

另外、“kintone iOS SDK”和以前发布的“kintone Node.js SDK”以及与本次同时期发布的“kintone Java SDK”的设计思路类似。
因此,虽然存在着开发语言的差异,但验证及连接、类、方法等各个地方的声明都一样。

GitHub

https://github.com/kintone-labs/kintone-ios-sdk/

文档

https://kintone-labs.github.io/kintone-ios-sdk/

本次通过范例对kintone iOS SDK的导入方法进行说明。
使用Xcode进行开发。请在可执行的环境下尝试。

Xcode

https://developer.apple.com/jp/xcode/

注意事项

  • 根据许可协议,可对代码进行更改、再发布以及用于商业目的。

导入方法

swift库的导入方法有使用包管理器和自己编译代码这两种方法。
本次介绍通过包管理器在Xcode的“Single View App”这个项目里进行导入的方法。
首先创建名字为“sample_project”的项目。

createProject.png

依次点击Xcode > Preferences > Locations,如下图设置命令行工具。

command-line-tools.png

安装

Cocoapods

主要包管理器的其中之一。
关于Cocoapods的安装请参考官网自行设置。

https://cocoapods.org/

在项目的安装目录下执行以下命令,创建Podfie。

$ pod init

参考以下范例,修改Podfile。

# Uncomment the next line to define a global platform for your project
platform :ios, '11.4'

target 'sample_project' do
  # Comment the next line if you're not using Swift and don't want to use dynamic frameworks
  use_frameworks!

  # Pods for sample_project
  pod 'kintone-ios-sdk', '~> 0.1.0'
  pod 'PromisesSwift', '~> 1.2.4'

  target 'sample_projectTests' do
    inherit! :search_paths
    # Pods for testing
  end

  target 'sample_projectUITests' do
    inherit! :search_paths
    # Pods for testing
  end

end

执行以下命令,可在Xcode项目内安装SDK。

$ pod install

执行命令后,将在目录下生成扩展名为“sample_project.xcworkspace”的文件。

用Xcode打开该文件,一旦编译后,即可在工作空间内使用SDK。

Carthage

Carthage可从Homebrew里安装。
请参考GitHub的文档自行安装。

https://github.com/Carthage/Carthage

在保存项目的目录下创建Cartfile。

$ touch Cartfile

请在Cartfile中输入以下内容。

github "google/promises"
github "kintone/kintone-ios-sdk"

Cartfile编辑完成后,执行以下命令,下载库。

$ carthage update

下载完成后,将在Sample_project/Carthage/Build/iOS文件夹内生成以下3个framework。

  • FBLPromises.framework

  • Promises.framework

  • kintone-ios-sdk.framework

需要将生成的framework文件导入到项目里。
请参考下图进行导入。

Carthage001.png

范例

使用文档Quickstart中的范例代码,对执行方法和应答进行说明。
范例代码的处理是从kintone应用中获取一条记录。
事前准备:创建kintone应用,根据下表添加字段,发行API令牌(必要权限=查看)。

字段类型字段代码
单行文本框text

范例代码(文件名:ViewController.swift)

复制以下范例代码,替换“sample_project”内的“ViewController.swift”。
API令牌、验证信息、子域名、应用ID等请根据自身的环境做适当的更改。

import UIKit
import FBLPromises
import kintone_ios_sdk

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view, typically from a nib.
        testGetRecord()
    }
    //Get Record Data
    func testGetRecord() {
        // This is an example of a functional test case.
        // Use XCTAssert and related functions to verify your tests produce the correct results.
        print("test start")
        
        let apitoken = "xxxxxx"
        let domain = "{yourdomain}.cybozu.cn"
        
        // Init authenticationAuth
        let kintoneAuth = Auth()
        kintoneAuth.setApiToken(apitoken)
        
        // Init Connection without "guest space ID"
        let kintoneConnection = Connection(domain, kintoneAuth)
        
        // Init Record Module
        let kintoneRecord = Record(kintoneConnection)
        
        // execute get record API
        let appID = xx
        let recordID = x
        kintoneRecord.getRecord(appID, recordID).then { response in
            let resultData = response.getRecord()!
            print(resultData["$id"]?.getValue())
            print(resultData["text"]?.getValue())
        }.catch { error in
            if error is KintoneAPIException {
                print((error as! KintoneAPIException).toString()!)
            }
        }
    }
}

执行

在Xcode上点击左上角的“▶︎”图标,或按⌘ + R来执行。

应答范例

请求成功时,返回以下应答。

response.png

范例代码解说

Authentication

对范例代码的第18~23行进行解说。
这部分是用于连接kintone,定义验证方法。

// Init authenticationAuth
let kintoneAuth = Auth()

可使用Authentication类,设置密码验证、API令牌验证、Basic验证。

验证的优先顺序如下。(参考:kintone REST API共通规格
1.密码验证
2.API令牌验证
※kintone iOS SDK不支持会话验证。

密码验证

let username = "User Name"
let password = "Password"
kintoneAuth.setPasswordAuth(username, password)

API令牌验证

let apiTokenString = "API Token";
kintoneAuth.setApiToken(apiTokenString);

Basic验证

let basicUsername = "Basic username";    
let basicPassword = "Basic password";    
kintoneAuth.setBasicAuth(basicUsername, basicPassword);

Connection

第26行是使用Connection类进行连接设置。
使用连接目标域名信息和刚才创建的验证信息连接到kintone。

let domain = "{subdomain}.cybozu.cn";
let kintoneConnection = Connection(domain, kintoneAuth);

// for GuestSpace
let domain = "{subdomain}.cybozu.cn";
let guestSpaceID = xx;
let kintoneConnection = Connection(domain, kintoneAuth, guestSpaceID);

Record

最后讲解第29~42行。

let kintoneRecord = Record(kintoneConnection)

// execute get record API
let appID = xx
let recordID = x
kintoneRecord.getRecord(appID, recordID).then { response in
    let resultData = response.getRecord()!
    print(resultData["$id"]?.getValue())
    print(resultData["text"]?.getValue())
}.catch { error in
    if error is KintoneAPIException {
        print((error as! KintoneAPIException).toString()!)
    }
}

这部分实际上是执行kintone的REST API的处理。

范例中,使用Record类的getRecord获取1条记录。

getRecord(appID, recordID)

参数

名称数据类型必须说明
appIDInteger应用ID
recordIDInteger记录编号

Record类里,如下文所述,除了获取1条记录外,还有其他各种各样的函数。

关于其他功能

Record类

此类中定义了如刚才范例代码中用到的函数等。
其定义的函数包含对应用的记录进行获取、添加、更新、删除、更改状态等类,
以及对回复进行获取、填写、删除等函数。

以下是其所包含的类的部分例子。

  • getRecord

  • getRecords

  • addRecord

  • addRecords

  • updateRecords

  • deleteRecords

  • updateRecordStatus

  • getComments

  • addComment

  • deleteComment

其他还有各种各样的函数。详情请参考文档。

关于Record类

https://kintone-labs.github.io/kintone-ios-sdk/reference/record/

BulkRequest类

可对多个应用同时发起多个API请求。
BulkRequest中可使用的函数请参考以下文档。

关于BulkRequest类

https://kintone-labs.github.io/kintone-ios-sdk/reference/bulk-request/

另外,执行BulkRequest时需要注意以下内容。

  • 执行BulkRequest并获取应答时,执行execute函数。

  • 除了excecute函数外,一次最多只能执行20个函数。

BulkRequest范例

var bulkRequest = BulkRequest(kintoneConnection);

bulkRequest = try! bulkRequest.addRecord(appID, addData)
bulkRequest = try! bulkRequest.addRecords(appID, addDataList)
bulkRequest = try! bulkRequest.updateRecordByID(appID, updRecID, updateData, nil)
bulkRequest = try! bulkRequest.deleteRecords(appID, delIdList);

bulkRequest.execute().then{ responses in
    print(responses)
}.catch{ error in
    if error is KintoneAPIException {
        print((error as! KintoneAPIException).toString()!)
    }
    else {
        print(error)
    }
}

App类

此类定义了用于获取应用信息的函数。
需要有应用的查看权限。
关于其包含的函数,请参考以下文档

关于App类

https://kintone-labs.github.io/kintone-ios-sdk/reference/app/

App范例

let app = App(kintoneConnection)

app.getApp(appID).then{ response in
    print(response.getCreator()?.getName())
}.catch{ error in
    if error is KintoneAPIException {
        print((error as! KintoneAPIException).toString()!)
    } else {
        print(error)
    }
}

关于类型

kintone iOS SDK中,各API的应答分别使用了独自的类型。

各自的构造函数以及可以使用的方法都不一样,使用前请认真阅读文档。

https://kintone-labs.github.io/kintone-ios-sdk/reference/model/app/app/app-model/

最后

在iOS及MacOS的应用开发过程中,可以更加方便地执行kintone REST API了。
希望您能借此机会好好利用kintone iOS SDK。

本Tips在2019年2月版 kintone中确认过。