検索
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=
  • セキュアアクセス設定環境にログインしたユーザーが、ログインユーザーと異なるユーザーの認証情報を使って JavaScript カスタマイズでの REST API を実行する場合、設定が必要です。
    利用するには「.com 共通管理」より「証明書のユーザーとパスワード認証のユーザーが異なるアクセスを許可する」を有効にしてください。
  • 2要素認証を設定したcybozu.com ユーザーアカウントでは、パスワード認証でREST APIを利用できません。

セッション認証

セッション認証とは、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環境）

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

パッケージ版（Linux環境）

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

レスポンス

HTTPステータスコードが「2xx」であれば正常終了、それ以外はエラー終了です。

エラーの詳細については、 Garoon ヘルプ - エラーメッセージ一覧　クラウド版・パッケージ版をご参照ください。

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

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

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

garoon.api()でリクエストした場合のレスポンスについて

garoon.api()でGaroon REST APIをリクエストした際、コールバックに渡される情報はレスポンスボディのみです。
そのため、レスポンスボディ以外の情報を利用する場合はgaroon.api()以外でリクエストする必要があります。

注意事項

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

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

制限事項

Garoon REST APIの同時実行制限があります。 それはREST API要求だけがカウントされます。デフォルト値は100です。

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

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

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

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