kaonavi API v2 (2.0)

最終更新日時: 2021/06/29 15:15

※このWebサイトは Internet Explorer には対応しておりません。Microsoft Edge など他のブラウザをご利用ください。

はじめに

kaonavi API v2 とは

kaonavi API v2 を使うことで、カオナビの各種データの取得・更新ができます。 こちらのドキュメントで、APIの使い方をご確認ください。

以前のバージョンについて

API v1系については、サポートサイトをご確認ください。

クイックスタート

概要

kaonavi API v2 は下記のようなHTTPリクエストで各種リソースの操作ができます。構成は以下の通りです。

$ curl -X {メソッド} https://api.kaonavi.jp/api/{バージョン}/{リソース} \
    -H 'Content-Type: application/json' \
    -H 'Authorization: {アクセストークン}'
  • {アクセストークン} ・・・接続可能な顧客情報を特定します。
  • {リソース} ・・・シートなどの各種情報を指定します。
  • {メソッド} ・・・GETやPUTなどを指定することで、取得、更新などの操作を行えます。

メソッドとリソースの組み合わせは左メニューのAPIリファレンス以下をご確認ください。

バージョン

最新バージョンは v2.0 です。

アクセストークンを発行する

認証のためのアクセストークンを発行しましょう。

認証情報の確認

アクセストークン発行のために必要な認証情報を事前に確認しておきます。 カオナビにログインし、 管理者機能トップ > 公開API v2 情報 > 認証情報 より、Consumer KeyConsumer Secret をご確認ください。

アクセストークン発行APIを実行

アクセストークン 発行 を参照して、アクセストークンを発行します。 アクセストークン発行に必要なcredentials の生成についてはBasicAuthを参照してください。

右側に記載されている Response samples のような内容が返ってきたら成功です。

{
  "access_token": "25396f58-10f8-c228-7f0f-818b1d666b2e",
  "token_type": "Bearer",
  "expires_in": 3600
}

access_token に記載されているものが、アクセストークンです。

メンバー情報 レイアウト定義を取得

これで準備完了です。メンバー情報のレイアウト定義の内容を取得してみましょう。 メンバー情報 レイアウト定義取得 を参照して、次のようなリクエストをしてください。

$ curl -X GET https://api.kaonavi.jp/api/v2.0/member_layouts \
    -H 'Content-Type: application/json' \
    -H 'Authorization: {アクセストークン}'

右側に記載されている Response samples のような内容が返ってきたら成功です。

メンバーの登録

kaonavi API v2 によるデータの登録や更新の多くは、非同期で行われます。 メンバー情報 登録 API を使って、メンバーを登録してみましょう。

メンバー登録タスクの作成

メンバー情報 登録 を参照して、次のようなリクエストをしてください。

$ curl -X POST https://api.kaonavi.jp/api/v2.0/members \
    -H 'Content-Type: application/json' \
    -H 'Authorization: {アクセストークン}' \
    -d '{
      "member_data": [
        {
          "code": "12345",
          "name": "カオナビ 太郎",
          "name_kana": "カオナビ タロウ"
        }
      ]
    }'

必須項目や最大文字数は先程取得したレイアウト定義取得APIの結果から確認できます。 右側に記載されている Response samples のような内容が返ってきたら成功です。これでメンバー登録のタスクが作成されました。

タスクの状況確認

次に、タスクの結果を確認してみましょう。

先程取得した task_id を利用して、タスク進捗状況 取得 を参照して、次のようなリクエストをしてください。

$ curl -X GET https://api.kaonavi.jp/api/v2.0/tasks/{task_id} \
    -H 'Content-Type: application/json' \
    -H 'Authorization: {アクセストークン}'

右側に記載されている Response samples のような内容が返ってきたら成功です。これで新しくメンバーが登録されたはずです。

以上でクイックスタートは終了です。左メニューのAPIリファレンス以下を参考に、様々なリソースを操作してみましょう。

リクエスト制限と推奨値

制限名称 説明
アクセストークンの有効期限 1時間
アクセストークンの最大同時払い出し数 1社につき毎時1,000回まで
リクエスト制限 1社につき毎時1,000回まで
更新リクエスト制限(※) 1社につき毎分5回まで
APIのステータスコードが200の場合のみ

※ 対象: メンバー情報, シート情報, 所属ツリー が制限の対象になります。

一回あたりの更新リクエストは以下を推奨しています。

  • データ件数(メンバー数 × シート項目数 × 複数レコードのレコード数): 100,000件以下
  • リクエストボディ: 10MB以下

dryrunモード

通常は本番モードで動作しますが、動作確認用にdryrunモードを用意しています。
通常のパラメータに加えて、ヘッダーに以下を設定することで、データベースの操作を行わず、リクエストの内容が適切であるかを検証することが出来ます。
※dryrunモードは登録・更新APIのみご利用いただけます。

ヘッダーパラメータ名
Dry-Run 0 または 1
結果
指定なし 本番モード
0を指定 本番モード
1を指定 dryrunモード
上記以外 パラメータエラー

リクエスト サンプル

$ curl -X POST https://api.kaonavi.jp/api/v2.0/members \
    -H 'Content-Type: application/json' \
    -H 'Authorization: {アクセストークン}' \
    -H 'Dry-Run: 1' \
    -d '{
      "member_data": [
        {
          "code": "12345",
          "name": "カオナビ 太郎",
          "name_kana": "カオナビ タロウ"
        }
      ]
    }'

レスポンスステータス

ステータスコード 説明
200 正常のレスポンス
400 パラメータにエラー
401 認証エラー
403 kaonavi API v2 の利用不可
404 存在しないIDを指定
405 存在しないメソッドを指定
429 アクセス回数制限を超えた
500 サーバーで予期せぬエラーが起きた
503 システムがメンテナンス中
504 タイムアウトエラー

custom_fields について

SETUP > レイアウト定義で設定したシートの項目情報はレイアウト定義APIにて custom_fields として取得できます。

更新可能なシート項目

パーツ サンプル 備考
テキストボックス
テキストエリア
ナンバーボックス
プルダウンリスト
ラジオボタン
チェックボックス
リンク https://www.kaonavi.jp
日付(カレンダー) 2021-01-01 YYYY-MM-DDの形式で更新してください
年月(カレンダー) 2021-01-01 YYYY-MM-DDの形式で更新してください
ファイル添付 image.jpg ファイル添付の使い方 をご確認ください
顔写真 A0001 顔写真パーツで表示させたいメンバーの社員番号を設定してください

更新できないシート項目

パーツ 備考
スペースエリア
タイトルボックス
メッセージボックス
計算式 登録・更新時に再計算されます
レーダーチャート

ファイル添付の使い方

こちら のページにあるCSVアップロードによるファイル名の事前設定作業の置き換えになるAPIです。以下の流れでファイルを添付することができます。

  1. アップロードする予定のファイル名を、APIで対象パーツに対して登録または更新する
  2. ファイル入出力画面から1で設定したパーツが含まれる対象シートを選び、設定したファイル名のファイルをアップロードする

注意

以下の場合を除き、既にファイル添付されているパーツに対し更新を行うと、事前に添付されていたファイルは削除されますのでご注意ください。

  • 単一レコードで、member_code , custom_fields.id , ファイル名 が一致している場合
  • 複数レコードでは、上記に加え、custom_fields.id 内のファイル名がレコードごとにユニークである場合

計算式パーツの取り扱い

直接値を更新することはできませんが、登録・更新API実行後、自動的に再計算処理が実行されます。

Authentication

BasicAuth

APIのアクセストークン取得にはconsumer_key、consumer_secretが必要です。

credentialsは次のように構築してください。

  1. consumer_keyとconsumer_secretをコロンで結合(consumer_key:consumer_secret)
  2. 1の文字列をBase64でエンコード

リクエスト サンプル

$ curl -X POST https://api.kaonavi.jp/api/v2.0/token \
    -H 'Authorization: Basic <credentials>'
    -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8'
    -d 'grant_type=client_credentials'
Security Scheme Type HTTP
HTTP Authorization Scheme basic

ApiKeyAuth

API実行にはアクセストークンが必要です。詳しくは アクセストークン 発行 を確認してください。
レスポンスから取得したアクセストークンは、API実行時にHTTPヘッダー(Kaonavi-Token)にセットして利用してください。

リクエスト サンプル

$ curl -X GET https://api.kaonavi.jp/api/v2.0/sheet_layouts \
    -H 'Kaonavi-Token: <access_token>'
Security Scheme Type API Key
Header parameter name: Kaonavi-Token

アクセストークン

アクセストークン 発行

アクセストークンを発行します。

Authorizations:
Request Body schema: application/x-www-form-urlencoded;charset=UTF-8
grant_type
required
string

client_credentials である必要があります。

Responses

Response samples

Content type
application/json
{
  • "access_token": "25396f58-10f8-c228-7f0f-818b1d666b2e",
  • "token_type": "Bearer",
  • "expires_in": 3600
}

レイアウト定義

メンバー情報 レイアウト定義取得

使用可能なメンバーのレイアウト定義情報を全て取得します。custom_fields の詳細については、custom_fields についてを参照ください。

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "code": {
    },
  • "name": {
    },
  • "name_kana": {
    },
  • "mail": {
    },
  • "entered_date": {
    },
  • "retired_date": {
    },
  • "gender": {
    },
  • "birthday": {
    },
  • "department": {
    },
  • "sub_departments": {