Documentation Powered by ReDoc

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

Download OpenAPI specification:Download

E-mail: api-tech-support@synergy101.jp URL: https://www.synergy-marketing.co.jp/cloud/synergy/ Terms of Service

はじめに

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

API の利用にあたって

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

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

認証

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

Synergy!データベースAPI にアクセスするためには、リクエストヘッダーに発行したクライアント認証キー、クライアントシークレットを使用して取得したアクセストークンを付与する必要があります。
アクセストークンは事前に Synergy! 認可サーバ (https://auth.paas.crmstyle.com/oauth2/token) から OAuth 2.0 のクライアント・クレデンシャルズフローにより取得します。
アクセストークンには有効期限が設定されており、切れるまでアクセストークンは有効です。Synergy!データベースAPI へアクセスするたびにアクセストークンを取得しないようにしてください。
アクセストークンの取得には、IPアドレス単位で1分間あたり最大100リクエストの上限を設けていますので、その上限を超えた場合はエラーを応答します。（HTTPステータスコード：429）
上限エラーとなった場合、再度アクセストークンを取得するには1分程度時間をあけてからアクセスする必要があります。

アクセストークン取得

リクエスト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
db:record:read ・Record.queryRecords
・Record.countRecords
・Record.getRecord
・Record.authenticate

リクエストサンプル

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 全般実行

  • db:record:read -

    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 をご参照ください。

リクエスト数制限

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

タイムアウト

データベースAPIのレスポンスは、対象データ件数、検索条件、システムの利用状況などにより時間がかかる場合があります。
通信タイムアウトの設定はご利用環境と用途に合わせて調整していただく必要がありますが、30秒以上に設定することを推奨します。

リトライ

GUIでのログイン処理や検索処理といった利用者が再実行可能な用途については混雑中をお伝えするなど、レスポンスステータスをチェックして適切な例外処理を設けてください。
API呼び出しでは通信状況など様々な要因で一時的にエラーが発生する可能性があるため、他システム連携など必要な手続きでは適切なリトライを設け処理を担保してください。
リトライの対象として、サーバーエラー（5xx）、リクエスト数制限エラー（429）、タイムアウトなどのネットワークエラーを考慮してください。
新規登録を行うリクエストでは、適切な更新キーをAPI 定義に含めることでリトライ時の重複登録を防止することが可能です。
複数回リトライを固定間隔にした場合、アクセス集中時に呼び出し間隔が収束するため、リクエスト数制限に達し易くなる傾向があります。
リクエスト数制限回避のため、リトライ間隔は固定値ではなく徐々に間隔を長くする「エクスポネンシャルバックオフ」と、可能でしたら一定の乱数を加味する「ジッター」を設け、分散させることをお勧めします。
また、最終的にAPIを実行できなかった際に、後からトレースができるようにAPI呼び出し元で適切なログを収集することをお勧めします。

改訂履歴

改訂日 更新内容
2023/12/12 アクセストークン取得時のレートリミットの説明を追加
プロパティの定義について追記
Synergy! 項目型一覧について追記
データ変換ルールを追加
2023/01/17 レコード参照のみを実行できる db:record:read スコープを追加
アクセストークンが不正である場合の説明を追記
customerDB項目作成による月額費用の変動についての注意文言を追記
2022/09/13 パスワード認証API（Record.authenticate）を追加
リソースにアクセスする権限が不足している場合の説明を追記
Record.findRecord を Record.getRecord に修正
2022/04/19 リクエスト数制限を レート：50/sec、バースト：200 から　レート：150/sec、バースト：300 に変更
2022/02/24 タイムアウトおよびリトライについて追記
2022/01/12 Record.findRecord の Response Sample を修正
2021/09/14 ApiDefinition.putApiDefinition 実行時の注意事項を追記
2021/07/27 DatabaseDefinition.listDatabaseDefinition および DatabaseDefinition.getDatabaseDefinition で返却される項目の並び順を管理画面のデータベース設計で設定された表示順で返却するよう修正
2021/06/29 選択肢のプロパティに required を補完するよう変更されたため example を修正
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 初版作成

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"
                    }
                  },
                • "required": [
                  • "value"
                  ]
                },
              • "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."
            }
          }
        }
      }
    ]
}

putApiDefinition

API 定義を登録・更新します。

登録済みの API 定義にプロパティを追加・削除することで API 定義を更新することができます。
なお、プロパティを削除しても定義していたデータベース項目は削除されません。 ただし、選択型項目については選択肢が削除される場合がありますのでご注意ください。くわしくはこちら。

API 定義について

Request samples を参考に API 定義を JSON 文字列で構築してリクエストボディに指定し、
リクエストヘッダーの Content-Type に application/json を指定してリクエストしてください。

データベースの設定

spec.resources.main にデータベースの名称および種別をセットします。

データベース名（mapping）について

  • 既存の Synergy! 上のデータベースが対象の場合
    DatabaseDefinition より定義したいデータベースの名称を取得して mapping にセットしてください。

  • 新しくデータベースを作成して定義を行う場合
    存在しないデータベース名を mapping にセットすることで、データベースを新規作成して API に定義することができます。
    新規作成できるのは type が historyDb の履歴型データベースのみです。
    アンダースコアから始まるデータベース名は予約されており、データベース新規作成時に指定することはできません。

データベース種別（type）について

定義したいデータベースのデータベース種別を type にセットしてください。
参照型データベースは使用できません。

定義名 説明
customerDb マスターデータベース
historyDb 履歴型データベース

プロパティの定義

spec.schema.properties にプロパティ名および型をセットします。
利用（または新規作成）したい項目のプロパティを定義してください。

プロパティ名について

定義対象のプロパティ名（key）にセットしてください。
プロパティ名は英小文字で始まり英数字またはアンダースコアで構成される必要があります。pattern: [a-z][a-zA-Z0-9_]*
新規作成可能な型かつ {API 定義名}_{プロパティ名} と同一の項目名がデータベースに存在しない場合、項目を新規作成して定義されます。
※customerDb（マスターデータベース）で作成した項目数により月額費用は変動します。詳しい料金に関しては、こちらを参照してください。

例）API 定義名が api1 プロパティ名が age の場合、データベース上の項目名は api1_age となります。

"metadata": {
  ...
  "name": "api1"
},
"spec": {
  ...
  "resources": {
    "properties": {
      "age": {
        "type": "number"
      },
      ...
    }
  }
}

型について

定義対象項目の項目型を Synergy! 項目型一覧 を参考に x-synergy-type にセットしてください。
x-synergy-typeをセットすることでtype および format を省略することが可能です。

  • 定義対象のデータベース種別により各 ID 型を定義する必要があります。
    データベース種別 説明
    マスターデータベース Synergy!ID 型をプロパティ名 id で定義してください。
    履歴型データベース HistoryID 型をプロパティ名 id で定義してください。
    Synergy!ID 型のプロパティを定義してください。

既存項目を定義する場合

既存項目を API に定義する

登録数上限

項目 上限数
登録可能な最大 API 定義数 10
1API のプロパティ（ApiDefinition.spec.schema.properties）数上限 100
Authorizations:
oauth (db:apidefinition:design) bearer
path Parameters
accountCode
required
string

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

name
required
string

API 定義名

Request Body schema: application/json

API 定義

object (ObjectMeta)

オブジェクトに共通のメタデータ

object (ApiDefinitionSpec)
object (ApiDefinitionStatus)

API 定義のステータス。読み取り専用。
データベース設定情報適用中などready.statusがtrueでない際にはAPIを利用することはできません。

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    • "kind": "ApiDefinition",
    • "apiVersion": "database/v1",
    • "name": "api1"
    },
  • "spec": {
    • "resources": {
      • "main": {
        • "mapping": "_customer",
        • "type": "customerDb"
        }
      },
    • "schema": {
      • "properties": {
        • "id": {
          • "x-synergy-type": "synergyId"
          },
        • "email": {
          • "x-synergy-type": "mailAddress"
          },
        • "createdAt": {
          • "x-synergy-type": "registeredDate"
          },
        • "updatedAt": {
          • "x-synergy-type": "updatedDate"
          },
        • "name": {
          • "type": "string"
          },
        • "age": {
          • "type": "number"
          },
        • "birthday": {
          • "type": "string",
          • "format": "date"
          },
        • "multipleSelect": {
          • "x-synergy-type": "multipleSelect",
          • "x-synergy-select-value-definitions": [
            • {
              • "value": 1,
              • "label": "select1",
              • "hasExtraText": false
              },
            • {
              • "value": 2,
              • "label": "select2",
              • "hasExtraText": true
              }
            ]
          }
        }
      }
    }
}

Response samples

Content type
application/json
{
  • "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"
                }
              },
            • "required": [
              • "value"
              ]
            },
          • "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."
        }
      }
    }
}

getApiDefinition

指定した定義名と一致する API 定義を取得します。

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

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

name
required
string

API 定義名

Responses

Response samples

Content type
application/json
{
  • "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"
                }
              },
            • "required": [
              • "value"
              ]
            },
          • "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."
        }
      }
    }
}

deleteApiDefinition

指定された定義名と一致する API 定義を削除します。
API 定義を削除しても定義されていたデータベース項目は削除されません。

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

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

name
required
string

API 定義名

Responses

Response samples

Content type
application/json
{
  • "timestamp": "string",
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "path": "string"
}

OpenApi

ApiDefinition で作成した API 定義を OpenAPI Document 形式で参照することができます。

getOpenApi

指定された API 定義の OpenAPI Document を取得します。

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

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

name
required
string

API 定義名

Responses

Response samples

Content type
application/json
application/json
application/x-yaml
application/yaml
{ }

getAllOpenApi

登録されている全てのAPI定義が内包されたOpenAPI Documentを取得します。

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

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

Responses

Response samples

Content type
application/json
application/json
application/x-yaml
application/yaml
{ }

DatabaseDefinition

Synergy! 内に登録されているデータベース設定情報を参照することができます。

listDatabaseDefinition

Synergy! 内に登録されているデータベース設定情報の一覧を取得します。

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": {
        • "apiVersion": "database/v1",
        • "kind": "DatabaseDefinition",
        • "accountCode": "xxxxx",
        • "name": "_customer",
        • "creationTimestamp": "2019-12-05T08:08:55.261Z",
        • "uid": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "resourceVersion": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "spec": {
        • "label": "マスターデータベース",
        • "type": "customerDb",
        • "columns": [
          • {
            • "name": "_synergyId",
            • "label": "Synergy!ID",
            • "type": "synergyId",
            • "synergySelectValueDefinitions": null
            },
          • {
            • "name": "name",
            • "label": "api1_name",
            • "type": "text",
            • "synergySelectValueDefinitions": null
            },
          • {
            • "name": "multipleSelect",
            • "label": "api1_multiple1",
            • "type": "array",
            • "synergySelectValueDefinitions": [
              • {
                • "value": 1,
                • "label": "select1",
                • "hasExtraText": false
                },
              • {
                • "value": 2,
                • "label": "select2",
                • "hasExtraText": true
                }
              ]
            }
          ]
        }
      },
    • {
      • "metadata": {
        • "apiVersion": "database/v1",
        • "kind": "DatabaseDefinition",
        • "accountCode": "xxxxx",
        • "name": "history_table",
        • "creationTimestamp": "2019-11-05T08:00:00.000Z",
        • "uid": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "resourceVersion": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "spec": {
        • "label": "履歴型データベース",
        • "type": "historyDb",
        • "columns": [
          • {
            • "name": "_historyId",
            • "label": "HistoryID",
            • "type": "historyId",
            • "synergySelectValueDefinitions": null
            },
          • {
            • "name": "_synergyId",
            • "label": "Synergy!ID",
            • "type": "synergyId",
            • "synergySelectValueDefinitions": null
            }
          ]
        }
      }
    ]
}

getDatabaseDefinition

指定されたデータベース設定情報を取得します。

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

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

name
required
string

データベース名

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    • "apiVersion": "database/v1",
    • "kind": "DatabaseDefinition",
    • "accountCode": "xxxxx",
    • "name": "_customer",
    • "creationTimestamp": "2019-12-05T08:08:55.261Z",
    • "uid": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    • "resourceVersion": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
  • "spec": {
    • "label": "マスターデータベース",
    • "type": "customerDb",
    • "columns": [
      • {
        • "name": "_synergyId",
        • "label": "Synergy!ID",
        • "type": "synergyId",
        • "synergySelectValueDefinitions": null
        },
      • {
        • "name": "name",
        • "label": "api1_name",
        • "type": "text",
        • "synergySelectValueDefinitions": null
        },
      • {
        • "name": "multipleSelect",
        • "label": "api1_multiple1",
        • "type": "array",
        • "synergySelectValueDefinitions": [
          • {
            • "value": 1,
            • "label": "select1",
            • "hasExtraText": false
            },
          • {
            • "value": 2,
            • "label": "select2",
            • "hasExtraText": true
            }
          ]
        }
      ]
    }
}

Record

ApiDefinition で作成した REST API を実行することができます。

createRecord

レコードを新規登録します。

Authorizations:
oauth (db:record:execute) bearer
path Parameters
accountCode
required
string

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

name
required
string

API 定義名

Request Body schema: application/json

登録対象のレコード

object

Responses

Request samples

Content type
application/json
{
  • "birthday": "YYYY-MM-DD",
  • "multipleSelect": [
    • {
      • "value": 2,
      • "extraText": "test"
      }
    ],
  • "name": "test-name",
  • "email": "xxxx@xxxx.com",
  • "age": 20
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "birthday": "YYYY-MM-DD",
  • "multipleSelect": [
    • {
      • "value": 2,
      • "extraText": "test"
      }
    ],
  • "name": "test-name",
  • "email": "xxxx@xxxx.com",
  • "age": 20
}

queryRecords

レコードを検索します。
filter オブジェクトを使用することで検索条件を設定できます。

Authorizations:
oauth (db:record:executedb:record:read) bearer
path Parameters
accountCode
required
string

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

name
required
string

API 定義名

Request Body schema: application/json

検索条件

limit
integer [ 1 .. 100 ]
Default: 100

1リクエストで取得したい最大アイテム数を指定してください。
検索件数が最大アイテム数を超えた場合、レスポンスの metadata.hasMore が true になります。

offset
integer >= 0
Default: 0

開始位置を指定してください。 未指定の場合、オフセットは省略されます。

object (RecordQueryFilter)

検索条件の設定

filter オブジェクトを活用することで SQL の WHERE 句のように条件を設定することができ、柔軟かつ複雑なクエリの構築が可能です。

filter オブジェクトの命名規則

filter オブジェクトの項目名は {propertyName}_{operator} のルールで命名されます。

例：名前が山田太郎のレコード

"filter": {
  "name_eq": "山田太郎"
}

オペレータ一覧

オペレータ一覧

AND オブジェクト

filter オブジェクト内の各オブジェクトは AND 句で結ばれています。
そのため、通常 AND オブジェクトは不要です。

例：年齢が20歳以上 かつ 60歳以下のレコード
"filter": {
  "age_gte": 20,
  "age_lte": 60
}

AND オブジェクトが必要な場合

contains オペレータまたは notContains オペレータを複数使用する場合、同一オペレータを複数指定することはできないため、AND オブジェクトを使用する必要があります。

例： メールアドレスに "@example.com", "@example.co.jp" が含まれないレコード
"filter": {
  "AND": [
    {
      "email_notContains": "@example.com"
    },
    {
      "email_notContains": "@example.co.jp"
    }
  ]
}

OR オブジェクト

配列内の各オブジェクトを使用した論理和を求めます。

例：メールアドレスの末尾が "@example.com" または "@example.co.jp" のレコード

"filter": {
  "OR": [
    {
      "email_endsWith": "@example.com"
    },
    {
      "email_endsWith": "@example.co.jp"
    }
  ]
}

Filter オブジェクトの制限

項目 上限数
設定可能な filter オブジェクト数 20
設定可能な filter オブジェクトの階層数 3
AND / OR の配列要素上限数 10
order
Array of strings <= 2 items

ソートキーとなるプロパティを指定してください。
未指定の場合、ASC（昇順）となります。

並び替えキーワード

  • ASC（昇順）
  • DESC（降順）

Responses

Request samples

Content type
application/json
{
  • "limit": 5,
  • "offset": 0,
  • "filter": {
    • "age_gte": 20,
    • "age_lte": 60
    },
  • "order": [
    • "id_desc"
    ]
}

Response samples

Content type
application/json
{
  • "metadata": {
    • "hasMore": false
    },
  • "items": [
    • {
      • "id": 2,
      • "birthday": "YYYY-MM-DD",
      • "multipleSelect": [
        • {
          • "value": 2,
          • "extraText": "string"
          }
        ],
      • "name": "string",
      • "email": "xxxx@xxxx.com",
      • "age": 60
      },
    • {
      • "id": 1,
      • "birthday": "YYYY-MM-DD",
      • "multipleSelect": [
        • {
          • "value": 1
          }
        ],
      • "name": "string",
      • "email": "xxxx@xxxx.com",
      • "age": 20
      }
    ]
}

countRecords

レコード件数を取得します。
filter オブジェクトを使用することで検索条件を設定できます。

Authorizations:
oauth (db:record:executedb:record:read) bearer
path Parameters
accountCode
required
string

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

name
required
string

API 定義名

Request Body schema: application/json

検索条件

object (RecordQueryFilter)

検索条件の設定

filter オブジェクトを活用することで SQL の WHERE 句のように条件を設定することができ、柔軟かつ複雑なクエリの構築が可能です。

filter オブジェクトの命名規則

filter オブジェクトの項目名は {propertyName}_{operator} のルールで命名されます。

例：名前が山田太郎のレコード

"filter": {
  "name_eq": "山田太郎"
}

オペレータ一覧

オペレータ一覧

AND オブジェクト

filter オブジェクト内の各オブジェクトは AND 句で結ばれています。
そのため、通常 AND オブジェクトは不要です。

例：年齢が20歳以上 かつ 60歳以下のレコード
"filter": {
  "age_gte": 20,
  "age_lte": 60
}

AND オブジェクトが必要な場合

contains オペレータまたは notContains オペレータを複数使用する場合、同一オペレータを複数指定することはできないため、AND オブジェクトを使用する必要があります。

例： メールアドレスに "@example.com", "@example.co.jp" が含まれないレコード
"filter": {
  "AND": [
    {
      "email_notContains": "@example.com"
    },
    {
      "email_notContains": "@example.co.jp"
    }
  ]
}

OR オブジェクト

配列内の各オブジェクトを使用した論理和を求めます。

例：メールアドレスの末尾が "@example.com" または "@example.co.jp" のレコード

"filter": {
  "OR": [
    {
      "email_endsWith": "@example.com"
    },
    {
      "email_endsWith": "@example.co.jp"
    }
  ]
}

Filter オブジェクトの制限

項目 上限数
設定可能な filter オブジェクト数 20
設定可能な filter オブジェクトの階層数 3
AND / OR の配列要素上限数 10

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "age_gte": 20,
    • "age_lte": 60
    }
}

Response samples

Content type
application/json
{
  • "count": 2
}

getRecord

ID で指定されたレコードを取得します。

Authorizations:
oauth (db:record:executedb:record:read) bearer
path Parameters
accountCode
required
string

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

name
required
string

API 定義名

id
required
string

レコード ID

Responses

Response samples

Content type
application/json
{
  • "id": 2,
  • "birthday": "YYYY-MM-DD",
  • "multipleSelect": [
    • {
      • "value": 2,
      • "extraText": "string"
      }
    ],
  • "name": "string",
  • "email": "xxxx@xxxx.com",
  • "age": 20
}

patchRecord

ID で指定されたレコードを更新します。

Authorizations:
oauth (db:record:execute) bearer
path Parameters
accountCode
required
string

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

name
required
string

API 定義名

id
required
string

レコード ID

query Parameters
fields
string

更新対象のフィールドをカンマ区切りで指定します。
指定されていない場合、リクエストボディで指定された JSON に含まれるフィールドがすべて更新対象になります。

Request Body schema: application/json

更新情報

object

Responses

Request samples

Content type
application/json
{
  • "birthday": "YYYY-MM-DD",
  • "multipleSelect": [
    • {
      • "value": 2,
      • "extraText": "string"
      }
    ],
  • "name": "string",
  • "email": "xxxx@xxxx.com",
  • "age": 25
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "birthday": "YYYY-MM-DD",
  • "multipleSelect": [
    • {
      • "value": 2,
      • "extraText": "string"
      }
    ],
  • "name": "string",
  • "email": "xxxx@xxxx.com",
  • "age": 25
}

deleteRecord

ID で指定されたレコードを削除します。

Authorizations:
oauth (db:record:execute) bearer
path Parameters
accountCode
required
string

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

name
required
string

API 定義名

id
required
string

レコード ID

Responses

Response samples

Content type
application/json
{
  • "timestamp": "string",
  • "status": 0,
  • "error": "string",
  • "message": "string",
  • "path": "string"
}

authenticate

パスワードハッシュ型項目でレコードの認証を行います。

Authorizations:
oauth (db:record:executedb:record:read) bearer
path Parameters
accountCode
required
string

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

name
required
string

API 定義名

id
required
string

レコード ID

Request Body schema: application/json

認証情報

propertyName
required
string

APIに定義されている項目のプロパティ名

value
required
string

パスワード

Responses

Request samples

Content type
application/json
{
  • "propertyName": "passwordHash",
  • "value": "Password"
}

Response samples

Content type
application/json
{
  • "result": "authenticated"
}

Appendix

Synergy! 項目型一覧

Synergy! 項目型 x-synergy-type 型 項目新規作成 備考
Synergy!ID synergyId integer × ・マスターデータベースを対象に API 定義する場合、プロパティ名を id にして定義してください
・履歴型データベースを対象に API 定義する場合、Synergy!ID は必須です
HistoryID historyId integer × ・履歴型データベースを対象に API 定義する場合、プロパティ名を id にして定義してください
ＰＣメールアドレス型 mailAddress string × email 形式
（e.g. synergy@example.com）
携帯メールアドレス型 mobileMailAddress string × email 形式
（e.g. synergy@example.com）
更新日時 updatedDate string × ISO 8601 形式
（e.g. 2020-05-01T00:00:00+09:00）
システム登録日時 registeredDate string × ISO 8601 形式
（e.g. 2020-05-01T00:00:00+09:00）
メール受信拒否フラグ型 mailRefusalFlag boolean × ・ご利用には Synergy! メール配信機能の契約が必要です
ＰＣメールエラーカウント型 mailAddressErrorCount integer × ・ご利用には Synergy! メール配信機能の契約が必要です
携帯メールエラーカウント型 mobileMailAddressErrorCount integer × ・ご利用には Synergy! メール配信機能の契約が必要です
メルマガ解除フラグリスト型 mlRefusalFlags array × ・ご利用には Synergy! メール配信機能の契約が必要です
文字型 text string ◯
数値型 number number ◯
年月日型 date string ◯ yyyy-MM-dd 形式（e.g. 2020-05-01）
月日型 monthDay string ◯ --MM-dd 形式（e.g. --05-01）
タイムスタンプ型 dateTime string ◯ ISO 8601 形式
（e.g. 2020-05-01T00:00:00+09:00）
単一選択型 singleSelect array ◯
複数選択型 multipleSelect array ◯
パスワード型 password string ◯
パスワードハッシュ型 passwordHash string ◯
  • 文字型、数値型、年月日型、タイムスタンプ型は type および format を指定することで、x-synergy-type を省略することができます。
Synergy! 項目型 type format
文字型 string -
数値型 number -
年月日型 string date
月日型 string month-day
タイムスタンプ型 string date-time

既存項目を API に定義する

Synergy!データベースAPI では、既に管理画面などからデータベースに設定されている項目を API に定義することができます。 対象の項目名を DatabaseDefinition から取得し、x-synergy-mapping にセットしてください。

既存項目マッピングサンプル
"spec": {
  ...
  "schema": {
    "properties": {
      "existingTxtColumn": {
        "x-synergy-mapping": "_col1",
        "type": "string"
      },
      "existingDateColumn": {
        "x-synergy-mapping": "_col2",
        "type": "string",
        "format": "date"
      },
      "existingPasswordColumn": {
        "x-synergy-mapping": "_col3",
        "x-synergy-type": "password"
      }
      "existingSingleSelectColumn": {
        "x-synergy-mapping": "_col4",
        "x-synergy-type": "singleSelect"
      }
    }
  }
}

putApiDefinition実行時の注意事項

API 定義更新時、x-synergy-select-value-definitions を使用して既存の選択型項目の選択肢を削除 / 編集すると、
意図せず選択肢定義を変更してしまうことがあります。

選択肢が変更された場合、管理画面での選択肢追加・変更を打ち消すような不整合が生じる可能性があります。
例えば、選択型項目に存在する選択肢を API 定義に含めずに更新すると、該当の選択肢は削除され、データベースに格納されている選択データも削除されます。

API定義から選択肢を管理しない場合は、x-synergy-select-value-definitionsを定義しないようにしてください。
選択肢の管理を行う場合は、API定義を更新する前に、最新の選択型項目の定義を DatabaseDefinition から取得し、 今から更新する選択肢内容が問題ないか確認してからAPI定義を更新してください。

オペレータ一覧

オペレータ 説明
eq 等しい
notEq 等しくない
isNull 対象が Null である
isNotNull 対象が Null でない
lt より小さい
lte 以下
gt より大きい
gte 以上
in いずれかと等しい
※ 右辺に複数の値を設定可能
notIn いずれとも等しくない
※ 右辺に複数の値を設定可能
contains 含んでいる
notContains 含んでいない
startsWith 対象の文字列で始まる
notStartsWith 対象の文字列で始まらない
endsWith 対象の文字列で終わる
notEndsWith 対象の文字列で終わらない
containsEvery 対象をすべて含んでいる
※ 右辺に複数の値を設定可能
containsSome 対象のいずれかを含んでいる
※ 右辺に複数の値を設定可能

型ごとの使用可能オペレータ

型 eq,
notEq		 isNull
isNotNull		 lt, lte,
gt, gte		 in,
notIn		 contains,
notContains		 startsWith,
notStartsWith,
endsWith,
notEndsWith		 containsEvery,
containsSome
Synergy!ID ○ × ○ ○ × × ×
HistoryID ○ × ○ ○ × × ×
ＰＣメールアドレス型 ○ ○ ○ ○ ○ ○ ×
携帯メールアドレス型 ○ ○ ○ ○ ○ ○ ×
更新日時 ○ × ○ ○ × × ×
システム登録日時 ○ × ○ ○ × × ×
メール受信拒否フラグ型 ○ × × × × × ×
ＰＣメールエラーカウント型 ○ × ○ ○ × × ×
携帯メールエラーカウント型 ○ × ○ ○ × × ×
メルマガ解除フラグリスト型 × ○ × × ○ × ○
文字型 ○ ○ ○ ○ ○ ○ ×
数値型 ○ ○ ○ ○ × × ×
年月日型 ○ ○ ○ ○ × × ×
月日型 ○ ○ ○ ○ × × ×
タイムスタンプ型 ○ ○ ○ ○ × × ×
単一選択型 ○ ○ ○ ○ × × ×
複数選択型 × ○ × × ○ × ○

データ変換

文字化けなどの問題を避けるため、DBAPIでは以下ルールで文字変換を行っております。

変換前 変換後
―
HORIZONTAL BAR
U+2015		 —
EM DASH
U+2014
～
FULLWIDTH TILDE
U+FF5E		 〜
WAVE DASH
U+301C
∥
PARALLEL TO
U+2225		 ‖
DOUBLE VERTICAL LINE
U+2016
－
FULLWIDTH HYPHEN
U+FF0D		 −
MINUS SIGN
U+2212
￠
FULLWIDTH CENT SIGN
U+FFE0		 ¢
CENT SIGN
U+00A2
￡
FULLWIDTH POUND SIGN
U+FFE1		 £
POUND SIGN
U+00A3
￢
FULLWIDTH NOT SIGN
U+FFE2		 ¬
NOT SIGN
U+00AC

サンプルコード

データベースAPI(ver1.0.0) を実行するサンプルプログラムです。