Download OpenAPI specification:Download
Synergy!データベースAPI は外部のシステムから、Synergy! のデータベース(マスター・履歴)の読み出し、登録・更新・削除などを簡単に行うことができる API です。
Synergy! の豊富な機能を生かしたシステム開発を簡易・短期間に行うことが可能です。
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 へアクセスするたびにアクセストークンを取得しないようにしてください。
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 名 | アクセス可能な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"
}
プロパティ名 | 型 | 説明 |
---|---|---|
access_token | String | Synergy!データベースAPI にアクセスするためのアクセストークンです。 |
expires_in | Integer | アクセストークンの有効期限が切れるまでの秒数を表します。 有効期限は1時間です。 |
scope | String | アクセストークンに含まれる scope の一覧を表します。 |
token_type | String | トークンの種別を表します。 bearer 固定です。 |
リクエストの際、Authorization ヘッダーにアクセストークンをセットしてください。
curl -X GET \
-H "accept: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
https://db.paas.crmstyle.com/apis/apidefinition.database/v1/accounts/{accountCode}/apidefinitions
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:
|
認証をご参照ください。
データモデルを OpenAPI V3 Schema 形式で定義し ApiDefinition.putApiDefinition から定義を登録します。
定義を登録することで Synergy! データベースに項目が作成され API に紐付けされます。Synergy! データベースに作成されている既存項目を定義登録に使用したい場合、既存項目を API に定義する を参照してください。
2で登録された API を Record より実行してください。
作成された API は OpenAPI Specification で定義されています。 OpenApi より OpenAPI Document を取得することで、ご利用の開発言語に応じて API クライアントの自動生成が可能です。 コード生成ツールは OpenAPI.Tools をご参照ください。
同時リクエスト数の制限には、トークンバケットモデル(アカウントごとに、レート:50/sec、バースト:200)を採用しています。
ブロック発生時は、レスポンスコード:429 Too Many Requests
を返しますので、数分後に再度お試しください。
改訂日 | 更新内容 |
---|---|
2021/01/26 | Record.createRecord, Record.patchRecord で 409 エラーが返却されることを追記 |
2020/12/15 | リクエスト数制限を レート:10/sec、バースト:100 から レート:50/sec、バースト:200 に変更 |
2020/10/02 | Record.queryRecords の件数上限判定について記載 |
2020/07/28 | Filter オブジェクトの階層制限について記載 isNotNull オペレータについて追記 複数選択型およびメルマガ解除フラグリスト型が isNull, isNotNull オペレータ使用可能になることを記載 Record のエラーレスポンスについて追記 |
2020/06/30 | サンプルコード(PHP)のリンクを追加 nullable 補完について記載 |
2020/06/08 | オブジェクト名にパターンに関する注意事項を追記 |
2020/05/27 | データベースごとに必要な ID 型を明記 アクセストークンの注意事項を追記 |
2020/05/19 | 初版作成 |
登録されている API 定義の一覧を取得します。
accountCode required | string API 管理画面に記載されたアカウントコード |
continueToken | string ページ送りのためのパラメーターです。 |
limit | integer [ 1 .. 100 ] Default: 100 1リクエストで取得したい最大アイテム数を指定してください。 |
{- "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
}
}
}, - "status": {
- "ready": {
- "lastUpdatedTimestamp": "2020-05-12T10:05:53.658468Z",
- "status": true,
- "message": "api is ready."
}, - "databaseDefinitionSync": {
- "lastUpdatedTimestamp": "2020-05-12T10:05:53.658468Z",
- "status": true,
- "message": "success."
}
}
}
}
]
}
API 定義を登録・更新します。
登録済みの API 定義にプロパティを追加・削除することで API 定義を更新することができます。
なお、プロパティを削除しても定義していたデータベース項目は削除されません。
Request samples を参考に API 定義を JSON 文字列で構築してリクエストボディに指定し、
リクエストヘッダーの Content-Type
に application/json
を指定してリクエストしてください。
spec.resources.main
にデータベースの名称および種別をセットします。
既存の Synergy! 上のデータベースが対象の場合
DatabaseDefinition より定義したいデータベースの名称を取得して mapping
にセットしてください。
新しくデータベースを作成して定義を行う場合
存在しないデータベース名を mapping
にセットすることで、データベースを新規作成して API に定義することができます。
新規作成できるのは type が historyDb の履歴型データベースのみです。
アンダースコアから始まるデータベース名は予約されており、データベース新規作成時に指定することはできません。
定義したいデータベースのデータベース種別を type
にセットしてください。
参照型データベースは使用できません。
定義名 | 説明 |
---|---|
customerDb | マスターデータベース |
historyDb | 履歴型データベース |
spec.schema.properties
にプロパティ名および型をセットします。
定義対象のプロパティ名(key)にセットしてください。
プロパティ名は英小文字で始まり英数字またはアンダースコアで構成される必要があります。pattern: [a-z][a-zA-Z0-9_]*
新規作成可能な型かつ {API 定義名}_{プロパティ名} と同一の項目名がデータベースに存在しない場合、項目を新規作成して定義されます。
例)API 定義名が api1
プロパティ名が age
の場合、データベース上の項目名は api1_age
となります。
"metadata": {
...
"name": "api1"
},
"spec": {
...
"resources": {
"properties": {
"age": {
"type": "number"
},
...
}
}
}
定義対象項目の項目型を Synergy! 項目型一覧 を参考に x-synergy-type
にセットしてください。
文字型
、数値型
、年月日型
、タイムスタンプ型
は type
および format
を指定することで、x-synergy-type を省略することができます。
Synergy! 項目型 | type | format |
---|---|---|
文字型 | string | - |
数値型 | number | - |
年月日型 | string | date |
月日型 | string | month-day |
タイムスタンプ型 | string | date-time |
定義対象のデータベース種別により各 ID 型を定義する必要があります。
データベース種別 | 説明 |
---|---|
マスターデータベース | Synergy!ID 型をプロパティ名 id で定義してください。 |
履歴型データベース | HistoryID 型をプロパティ名 id で定義してください。 Synergy!ID 型のプロパティを定義してください。 |
項目 | 上限数 |
---|---|
登録可能な最大 API 定義数 | 10 |
1API のプロパティ(ApiDefinition.spec.schema.properties)数上限 | 100 |
accountCode required | string API 管理画面に記載されたアカウントコード |