Synergy!データベースAPI (1.1.0)

Download OpenAPI specification:Download

はじめに

Synergy!データベースAPI は外部のシステムから、Synergy! のデータベース(マスター・履歴)の読み出し、登録・更新・削除などを簡単に行うことができる API です。
Synergy! の豊富な機能を生かしたシステム開発を簡易・短期間に行うことが可能です。

API の利用にあたって

API をご利用いただく場合、事前に Synergy! の利用登録が必要になります。
利用登録がまだお済みでない方は Synergy! 公式ページよりお問い合わせください。

また、API の利用には Synergy! データベース API 契約規定 が適用され、API を利用すると契約規定に同意したものとみなされます。

認証

管理画面上の API 管理からクライアント認証キー、クライアントシークレットの発行を行なってください。 発行時アクセス可能な IP アドレスを設定することで、指定した IP アドレス以外からのリクエストを制限することができます。

Synergy!データベースAPI にアクセスするためには、リクエストヘッダーに発行したクライアント認証キー、クライアントシークレットを使用して取得したアクセストークンを付与する必要があります。
アクセストークンは事前に Synergy! 認可サーバ (https://auth.paas.crmstyle.com/oauth2/token) から OAuth 2.0 のクライアント・クレデンシャルズフローにより取得します。
アクセストークンには有効期限が設定されており、切れるまでアクセストークンは有効です。Synergy!データベースAPI へアクセスするたびにアクセストークンを取得しないようにしてください。

アクセストークン取得

リクエストURL

https://auth.paas.crmstyle.com/oauth2/token

リクエストヘッダー

フィールド名 内容
Content-Type application/x-www-form-urlencoded
Authorization 管理画面上の API 管理からクライアント認証キー、クライアントシークレットの発行が可能となります。
クライアント認証キー、クライアントシークレットを:(コロン)で繋いで、base64 でエンコードした文字列を指定します。

リクエストパラメーター

プロパティ名 説明
grant_type String OAuth 2.0 の処理フローを表します。
"client_credentials" を指定してください。
audience String アクセスするAPIのドメインを表します。
"https://db.paas.crmstyle.com" を指定してください。
scope String アクセスするAPIの種別を表します。
複数指定する場合は半角スペースを scope の間に含めて指定してください。

scope一覧

scope 名 アクセス可能なAPI
db:apidefinition:design ・ApiDefinition
・OpenApi
・DatabaseDefinition
db:openapi:read ・OpenApi
db:record:execute ・Record

リクエストサンプル

AUTHHEADER=`echo -n ${CLIENT_ID}:${CLIENT_SECRET} | base64 -w0`  
SCOPES="db:apidefinition:design db:openapi:read db:record:execute"
curl -i -X POST \
  -H "Authorization: Basic ${AUTHHEADER}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  https://auth.paas.crmstyle.com/oauth2/token \
  -d "grant_type=client_credentials&scope=${SCOPES}&audience=https://db.paas.crmstyle.com"

レスポンス

レスポンスは JSON 形式で返却されます。

レスポンスサンプル
{
  "access_token": "{Access Token}",
  "expires_in": 3599,
  "scope": "db:apidefinition:design db:openapi:read db:record:execute",
  "token_type": "bearer"
}
レスポンス JSON プロパティ
プロパティ名 説明
access_token String Synergy!データベースAPI にアクセスするためのアクセストークンです。
expires_in Integer アクセストークンの有効期限が切れるまでの秒数を表します。
有効期限は1時間です。
scope String アクセストークンに含まれる scope の一覧を表します。
token_type String トークンの種別を表します。
bearer 固定です。

Synergy!データベースAPI リクエスト

リクエストの際、Authorization ヘッダーにアクセストークンをセットしてください。

listApiDefinition リクエストサンプル

curl -X GET \
  -H "accept: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  https://db.paas.crmstyle.com/apis/apidefinition.database/v1/accounts/{accountCode}/apidefinitions

oauth

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: https://auth.paas.crmstyle.com/oauth2/token
Refresh URL: https://auth.paas.crmstyle.com/oauth2/token
Scopes:
  • db:apidefinition:design -

    ApiDefinition 全般実行、OpenApi 定義参照、データベース設定情報参照

  • db:openapi:read -

    OpenApi 定義参照のみ可能

  • db:record:execute -

    Record 全般実行

bearer

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

ご利用までの流れ

1. 認証情報取得

認証をご参照ください。

2. Record 定義登録

データモデルを OpenAPI V3 Schema 形式で定義し ApiDefinition.putApiDefinition から定義を登録します。
定義を登録することで Synergy! データベースに項目が作成され API に紐付けされます。Synergy! データベースに作成されている既存項目を定義登録に使用したい場合、既存項目を API に定義する を参照してください。

3. Record 利用

2で登録された API を Record より実行してください。

APIクライアントについて

作成された API は OpenAPI Specification で定義されています。 OpenApi より OpenAPI Document を取得することで、ご利用の開発言語に応じて API クライアントの自動生成が可能です。 コード生成ツールは OpenAPI.Tools をご参照ください。

リクエスト数制限

同時リクエスト数の制限には、トークンバケットモデル(アカウントごとに、レート:10/sec、バースト:100)を採用しています。
ブロック発生時は、レスポンスコード:429 Too Many Request を返しますので、数分後に再度お試しください。

改訂履歴

改訂日 更新内容
2020/07/28 Filter オブジェクトの階層制限について記載
isNotNull オペレータについて追記
複数選択型およびメルマガ解除フラグリスト型が isNull, isNotNull オペレータ使用可能になることを記載
Record のエラーレスポンスについて追記
2020/06/30 サンプルコード(PHP)のリンクを追加
nullable 補完について記載
2020/06/08 オブジェクト名にパターンに関する注意事項を追記
2020/05/27 データベースごとに必要な ID 型を明記
アクセストークンの注意事項を追記
2020/05/19 初版作成

ApiDefinition

サーバ間連携用の独自の REST API を作成することができます。

listApiDefinition

登録されている API 定義の一覧を取得します。

Authorizations:
oauth (db:apidefinition:design) bearer
path Parameters
accountCode
required
string

API 管理画面に記載されたアカウントコード

query Parameters
continueToken
string

ページ送りのためのパラメーターです。
取得アイテム数が limit で指定した最大アイテム数を超過した場合に値が返却されます。 continueToken をリクエストパラメーターに指定することで limit 以降のアイテムを取得できます。

limit
integer [ 1 .. 100 ]
Default: 100

1リクエストで取得したい最大アイテム数を指定してください。
未指定の場合、100 になります。

Responses

Response samples

Content type
application/json
{
  • "metadata":
    {
    • "continueToken": "string"
    },
  • "items":
    [
    • {
      • "metadata":
        {
        • "kind": "ApiDefinition",
        • "name": "api1",
        • "apiVersion": "database/v1",
        • "accountCode": "xxxxx",
        • "creationTimestamp": "2019-12-05T08:08:55.261Z",
        • "uid": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "resourceVersion": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "spec":
        {
        • "resources":
          {
          • "main":
            {
            • "mapping": "_customer",
            • "type": "customerDb"
            }
          },
        • "schema":
          {
          • "properties":
            {
            • "id":
              {
              • "x-synergy-type": "synergyId",
              • "x-synergy-mapping": "_synergyId",
              • "type": "integer"
              },
            • "email":
              {
              • "x-synergy-type": "mailAddress",
              • "x-synergy-mapping": "_mailAddress",
              • "type": "string",
              • "format": "email",
              • "nullable": true
              },
            • "createdAt":
              {
              • "x-synergy-type": "registeredDate",
              • "x-synergy-mapping": "_registeredDate",
              • "type": "string",
              • "format": "date-time"
              },
            • "updatedAt":
              {
              • "x-synergy-type": "updatedDate",
              • "x-synergy-mapping": "_updatedDate",
              • "type": "string",
              • "format": "date-time"
              },
            • "name":
              {
              • "x-synergy-type": "text",
              • "x-synergy-mapping": "api1_name",
              • "type": "string",
              • "nullable": true
              },
            • "age":
              {
              • "x-synergy-type": "number",
              • "x-synergy-mapping": "api1_age",
              • "type": "number",
              • "nullable": true
              },
            • "birthday":
              {
              • "x-synergy-type": "date",
              • "x-synergy-mapping": "api1_birthday",
              • "type": "string",
              • "format": "date",
              • "nullable": true
              },
            • "multipleSelect":
              {
              • "x-synergy-type": "multipleSelect",
              • "x-synergy-mapping": "api1_multiple1",
              • "x-synergy-select-value-definitions":
                [
                • {
                  • "value": 1,
                  • "label": "select1",
                  • "hasExtraText": false
                  },
                • {
                  • "value": 2,
                  • "label": "select2",
                  • "hasExtraText": true
                  }
                ],
              • "type": "array",
              • "items":
                {
                • "type": "object",
                • "properties":
                  {
                  • "extraText":
                    {
                    • "type": "string",
                    • "nullable": true
                    },
                  • "value":
                    {
                    • "type": "integer"
                    }
                  }
                },
              • "nullable": true
              }
            }
          },