検索
Close
カテゴリー内の他の記事

Garoon REST APIの共通仕様

作成日
更新日

次期Garoon REST APIに関するアンケートにご協力ください。

Index

Garoon REST APIの概要

Garoon のデータを取得、登録、更新、削除することができます。

プロトコル

HTTPS

フォーマット

JSON

文字コード

UTF-8

エスケープ文字

「\」を使用します。

ユーザー認証

APIを実行するリクエストには、認証のためのヘッダを追加する必要があります。

パスワード認証

  • リクエストヘッダに「X-Cybozu-Authorization」を追加し、「ログイン名:パスワード」をBASE64エンコードしたものを値に指定します。
// ログイン名が「Administrator」、パスワードが「cybozu」の場合
X-Cybozu-Authorization:QWRtaW5pc3RyYXRvcjpjeWJvenU=
  • 2要素認証を設定したcybozu.com ユーザーアカウントでは、パスワード認証でREST APIを利用できません。

  • kintone や Garoon から パスワード認証を使って Garoon REST API を実行した後は、再度ログインを求められるようになります。
    kintone や Garoon の JavaScript カスタマイズで、XMLHttpRequest や Fetch API などを使って Garoon REST API を実行するときは、リクエストトークンを利用してください。

    kintone や Garoon のカスタマイズファイルにパスワードなどの認証情報をハードコーディングすることは、認証情報が漏洩する恐れがあるため、推奨していません。
    詳しくは、セキュアコーディングガイドラインを確認してください。

セッション認証

セッション認証とは、Webサーバから付与されたセッションIDをCookieに保存する事でユーザを識別する認証方法です。
※ POST、PATCH、DELETEでは、セッション認証の場合は、RequestTokenが必要です。詳しくは Garoon CSRFトークンの利用例 の記事をご確認ください。

認証時の優先順位について

優先順位は以下の通りです。

  1. パスワード認証
  2. セッション認証

OAuthクライアントを使用して認証することも出来ます。詳細はこちらを参照してください。

SAML認証設定時の利用について

SAML認証設定時に、cybozu.comのパスワード認証、セッション認証、OAuthクライアントを使用した認証でGaroon REST APIを利用できます。
cybozu.com のログイン時に SAML 認証のみを使うように制限している場合、パスワード認証による Garoon REST API の実行がcybozu.com共通管理者のみに制限されます。セッション認証、OAuthクライアントを使用した認証の場合、この制限を受けません。

Basic認証

cybozu.com でBasic認証を利用している場合は、更にリクエストヘッダに「Authorization」ヘッダを追加し、「Basic 」と「ログイン名:パスワード」をBASE64エンコードしたものを値に指定します。

  • 「Basic」 と 「ログイン名:パスワード」 の間は、半角空白が必要です。
  • 「Basic」の BASE64エンコードは不要です。
// ログイン名が「Administrator」、パスワードが「cybozu」の場合
Authorization:Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=

リクエスト

リクエストヘッダ

送信するリクエストに応じて以下のリクエストヘッダを指定します。

ヘッダー名 必須 内容
Host 必須 (サブドメイン名).cybozu.com:443
Content-Type

省略可

application/json
※リクエストボディにJSON文字列を格納する場合のみ指定します。

X-Cybozu-Authorization

省略可
※パスワード認証を利用している場合必須

 「ログイン名:パスワード」をBASE64エンコードしたものを値に指定します。
X-Requested-With

省略可
※セッション認証を利用している場合必須

 XMLHttpRequest または空文字列以外の文字列
Authorization 省略可 Basic認証を利用している場合、文字列「Basic」と「ログイン名:パスワード」をBASE64エンコードしたものを値に指定します。

リクエストURI

クラウド版

https://(サブドメイン名).cybozu.com/g/api/v1/(アプリケーション名)/(リソース)

パッケージ版（Windows環境）

以下は、ヘルプに記載しているWindows のディレクトリー構成でインストールしたときの例です。インストールするディレクトリーを変更している場合は、パスを読み替えてください。

http://(サーバーのIPアドレスまたはホスト名)/scripts/(インストール識別子)/grn.exe/api/v1/(アプリケーション名)/(リソース)

パッケージ版（Linux環境）

以下は、ヘルプに記載しているLinux のディレクトリー構成でインストールしたときの例です。インストールするディレクトリーを変更している場合は、パスを読み替えてください。

http://(サーバーのIPアドレスまたはホスト名)/cgi-bin/(インストール識別子)/grn.cgi/api/v1/(アプリケーション名)/(リソース)

レスポンス

リクエストに成功した場合、200 番台のステータスコードが返ります。
リクエストに失敗した場合、200 番台以外のステータスコードと、次のプロパティを持つオブジェクトが返されます。
エラー内容の詳細は、エラーメッセージ一覧（クラウド版／パッケージ版）を参照してください。

パラメータ名 型 説明
errorCode 文字列 エラーの種類を表すコード
message 文字列 エラーメッセージ
API を実行したユーザーの表示言語の設定によって、異なります。
cause 文字列 エラーの原因

 

すべてのGaroon REST APIのレスポンスヘッダには、次の情報が含まれています。

ヘッダー名 内容
X-ConcurrencyLimit-Limit

同時接続数の上限値
固定値の100です。
X-ConcurrencyLimit-Running 現在の同時接続数

注意事項

IPアドレス制限を行っている環境に対するREST APIリクエストについては、次のAPIリクエストがアクセス可能です。

  • アクセス許可されたIPアドレスがアクセス元となるAPIリクエスト
  • アクセス許可されたクライアント証明書を利用したAPIリクエスト

制限事項

  • Garoon REST APIの同時実行制限があります。 それはREST API要求だけがカウントされます。デフォルト値は100です。
  • Garoon REST APIを利用して添付ファイルをアップロードする場合、ガルーンのシステム設定で、
    ファイルサイズの上限値が「無制限」の場合も、アップロード可能なファイルサイズの上限は BASE64エンコード後の状態で 300MB になります。

その他、サービスに関する制限事項は、cybozu.comの制限事項 をご確認ください。

記事に関するフィードバック

記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。

サインインしてコメントを残してください。