検索
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=

  • kintone や Garoon から パスワード認証を使って Garoon REST API を実行した後は、再度ログインを求められるようになります。

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

セッション認証

Garoon や kintone に適用した JavaScript ファイルから Garoon REST API を実行する場合には、セッションによる認証を利用できます。

OAuth を使った認証

OAuthクライアントを使用して認証することもできます。
詳細は、OAuthクライアントの使用を参照してください。

認証方式の優先順位

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

  1. パスワード認証
  2. OAuth を使った認証
  3. セッション認証

セキュリティ設定を行った環境での API の利用

IP アドレス制限を設定している場合

IP アドレス制限を設定している場合には、次のいずれかの方法で Garoon REST API を実行します。

  • Garoon REST API を実行するサーバーの IP アドレスを許可する
    許可する方法は、ヘルプページを参照してください。
  • Basic 認証を設定している場合は、「Authorization」リクエストヘッダを付与する
    詳細は、Basic 認証を参照してください。
  • 有効期限の過ぎていないクライアント証明書を付与する
    詳細は、クライアント証明書を参照してください。

Basic認証

IP アドレス制限に加え、Basic 認証を設定している場合は、リクエストヘッダに「Authorization」ヘッダを追加します。

  • 「Basic 」と「ログイン名:パスワード」をBASE64エンコードしたものを、「Authorization」ヘッダの値に指定します。
    • 「Basic」 と 「ログイン名:パスワード」 の間は、半角空白が必要です。
    • 「Basic」の BASE64エンコードは不要です。
// ログイン名が「Administrator」、パスワードが「cybozu」の場合
Authorization:Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=

クライアント証明書

クライアント証明書は、ユーザーに利用サービスの「セキュアアクセス」を許可することで発行できるようになります。
セキュアアクセスの利用を許可し、クライアント証明書を発行する方法は、セキュアアクセスを設定するを参照してください。

  • リクエストする URLには、.s を付ける必要があります。
    たとえば、URL が https://sample.cybozu.com の場合は、https://sample.s.cybozu.com です。

SAML認証を設定している場合

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

2要素認証を設定している場合

2要素認証を設定した cybozu.com ユーザーアカウントでは、パスワード認証は利用できません。

パスワード認証以外の認証方式で実行するか、2要素認証を無効にした連携用のユーザーを用意してください。

リクエスト

リクエストヘッダ

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

ヘッダー名 必須 内容
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 現在の同時接続数

 

制限事項

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

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

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

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

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