スキーマの定義

このトピックではカスタムコネクタとその関連引数に必要なルートレベルのプロパティ、カスタムコネクタの範囲と制限、および使用する API の要件について説明します。「範囲と制限」を参照してください。

schema

schema プロパティでコネクタのスキーマバージョンを指定します。

プロパティ タイプ 必須 例
schema string はい The version of the schema used

name

name プロパティでコネクタの名前を指定します。このプロパティは UI に表示されます。「コネクタの視覚的プロパティ」を参照してください。

プロパティ タイプ 必須 例
name string はい My custom connector

description

description プロパティでコネクタの説明を指定します。このプロパティは UI に表示されます。「コネクタの視覚的プロパティ」を参照してください。

プロパティ タイプ 必須 例
description string いいえ My custom connector description

auth_components

auth_components オブジェクトでサードパーティの API の認証に必要なプロパティを指定します。API の中には認証を必要としないものもあれば、OAuth1 など特定の種類の認証方法を必要とするものもあります。

プロパティ タイプ 必須
type

string

 はい

requiredSettings

requiredSettings オブジェクトで API の通信に必要なプロパティを指定します。

プロパティ タイプ 必須 説明
authFields array はい 認証に必要なフィールド

requiredSettings (authFields)

authFields 配列で API の認証に必要なフィールドを指定します。認証を必要としない API の場合、authFields 配列は空のままにします。

プロパティ タイプ 必須 説明 例

label

 string いいえ 認証フィールドのラベル Access Token
key string いいえ 認証フィールドのキー access_token
description string いいえ 認証フィールドの説明 My field description
errorText string いいえ 特定のエラーシナリオの説明 My error message
masked boolean いいえ フィールドの値をマスクして機密情報を非表示にするかどうか True
choices object いいえ ユーザが選択できる値のプルダウンリスト { options_a: "Option A", options_b: "Option B"}
preAddOn string いいえ 認証フィールドの前に付加できる値 "https://"
emptyAllowed boolean いいえ 認証フィールドの値を空にできるかどうか True
extLink string いいえ 外部ドキュメンテーションへのリンク https://help.claris.com/ja/connect-help/
postAddOn string いいえ 認証フィールドの前に付加できる値 example.com

auth_request

auth_request オブジェクトで API と通信して現在のユーザのアクセスレベルを決定するときに使用する認証リクエストのタイプを指定します。

プロパティ タイプ 必須 説明 認証タイプ 例
type string はい 認証リクエストのタイプ basic auth、bearer、custom、custom body、custom header、custom query、または none bearer
errorMessageKey string いいえ サードパーティ App の応答で見つかったエラーメッセージのキー すべて error.message
token string いいえ Bearer 認証のトークンプロパティ bearer '{{authFields.api_key}}'
headers object いいえ 認証リクエストに含まれる HTTP ヘッダ すべて { 'X-Algolia-API-Key': '{{authFields.api_key}}', 'X-Algolia-Application-Id': '{{authFields.app_id}}' }
query_parameters object いいえ 認証リクエストに含まれるクエリー引数 custom_query { access_token: '{{authFields.access_token}}' }
username string いいえ 基本認証に使用するユーザ名の属性 basic_auth '{{authFields.username}}'
password string いいえ 基本認証に使用するパスワードの属性 basic_auth '{{authFields.password}}'
body_parameters object いいえ 認証リクエストに含まれるボディ引数 custom_body { access_token: '{{authFields.access_token}}' }

endpoints

endpoints オブジェクトで API へのリクエストで使用する HTTP メソッド、API のターゲットリソース、およびリソースのルートパス (URL) を指定します。

たとえば、Claris Studio コネクタを使用して Claris Studio のテーブルからフィールドの一覧を返すには、https://api.platform.claris.com にあるリソースをターゲットとするネストされた /field オブジェクトを含む GET メソッドオブジェクトを挿入します。次の例を参照してください:

コピー 
"endpoints": {
      "GET": {
        "/field": {
          "url": "https://api.platform.claris.com"
        }
      }
    },
プロパティ タイプ 必須 説明 例
url string はい サードパーティ API のルート URL https://api.platform.claris.com
custom_behavior object いいえ カスタム動作オブジェクト  

endpoints (custom_behavior)

各リソースごとにオプションで custom_behavior オブジェクトを追加して、そのリソースに対して行われた HTTP リクエストのヘッダ、クエリー、およびボディにカスタムロジックを適用できます。

プロパティ タイプ 必須 説明
headers object いいえ リクエストで送信されるカスタムヘッダを指定するオブジェクト
body_options object いいえ

リクエストのボディ全体にカスタム動作を適用できるオブジェクト

send_as_urlencoded (boolean)

  • application/x-www-form-urlencoded の内容タイプとしてリクエストを送信するかどうかを指定します。

send_as_multipart (boolean)

  • multipart/form-data の内容タイプとしてリクエストを送信するかどうかを指定します。

actions

actions 配列でコネクタに含めるアクションと関連するプロパティを指定します。アクションは endpoints オブジェクトで指定されたリソースのエンドポイントを参照し、サードパーティの API から、またはサードパーティの API に送られるデータを操作するために使用します。

プロパティ タイプ 必須 説明 例
modelId string はい アクションのモデル ID。actionID で複合インデックスを作成します。 files
actionId string はい アクションのアクション ID。modelID で複合インデックスを作成します。 search
method string はい アクションの HTTP メソッド GET
endpoint string はい

アクションのリソースのエンドポイント。

メモ  エンドポイントパスでは変数も使用できます。「エンドポイント変数の使用」を参照してください。

 '/search'
isNotTestable boolean いいえ アクションがユーザによってテストできないかどうか True
label string いいえ アクションの名前 Search by query
helpText string はい アクションの説明 Search using a custom query
urlFields array いいえ アクションに含めるフィールドを指定するオブジェクト  
actionFields array はい アクションに含めるフィールドを指定するオブジェクト  

actionFields および urlFields

actionFields および urlFields オブジェクトでアクションのフィールドを指定してアクションの動作を制御します。urlFields および actionFields の一部の要素は UI に表示されます。「アクションの視覚的プロパティ」および「フィールドの視覚的プロパティ」を参照してください。

プロパティ タイプ 必須 説明 例
key string はい アクションの HTTP メソッド GET
helpText string いいえ フィールドのプレースホルダ値 Example: Value
type string いいえ フィールドのデータタイプ string
choices object いいえ 使用できる選択の一覧 "choiceA" : "Choice A", "choiceB" : "Choice B"
required boolean はい actionField または urlField が必要かどうか True

testConnection

testConnection オブジェクトで Claris Connect と API の間の接続をテストするために使用するプロパティを指定して認証の資格情報が有効であることを確認します。testConnection で指定された呼び出しは auth_request 設定を継承して API に対して認証するときに実行されます。

メモ  testConnection エンドポイントは endpoints オブジェクト内で指定する必要があります。オブジェクト外で指定した場合認証は失敗します。

プロパティ タイプ 必須 説明 例
endpoint string はい サードパーティ API への接続をテストするために使用するリソースのエンドポイント /users
queryParameters string いいえ サードパーティ API への接続をテストするために使用するリソースのエンドポイントに追加するクエリー引数 q=Claris
method string いいえ サードパーティ API への接続をテストするために使用する HTTP メソッド GET
body object いいえ サードパーティ API への接続をテストするために使用する HTTP リクエストのボディ {"text":"Connect"}

視覚的プロパティ

次の表はコネクタの作成後にスキーマのどのコンポーネントプロパティが UI に表示されるかを示しています。

コネクタ

connector オブジェクトのプロパティは [Select] タブでコネクタの (i) アイコンをクリックしたときに表示されるカードに対応しています。

プロパティ タイプ 必須 UI
name string はい カスタムコネクタ名
description string いいえ カスタムコネクタの説明

アクション

actions オブジェクトのプロパティはコネクタを選択した後に [Action] タブに表示されるアクションの一覧に対応しています。

プロパティ タイプ 必須 UI
label string はい カスタムコネクタアクション名
helpText string はい カスタムコネクタアクションの説明

フィールド (urlFields および actionFields)

fields オブジェクトのプロパティはコネクタからアクションを選択した後に [Configure] タブに表示されるフィールドに対応しています。

プロパティ タイプ 必須 UI
label string はい カスタムコネクタアクション、フィールド名
description string はい カスタムコネクタアクション、フィールドの説明
required string はい カスタムコネクタアクション、必須フィールド

エンドポイント変数の使用

endpoints オブジェクトで指定したエンドポイントへのパスには変数を含めることができます。変数はエンドポイントの一部で任意の値とコロン (:) で示されるプレースホルダです。たとえば、mydomain.com/api/myEndpoint/:myVariable などです。

actions または testConnection オブジェクトで 変数を含む endpoints を使用するには、次の 3 つを行う必要があります:

  1. endpoints オブジェクトで、エンドポイントを宣言します。

  2. アクション配列内の urlFields 配列で、エンドポイントで使用する変数と同じ値で "key" 属性を指定します。
    たとえば、エンドポイント変数が :id の場合、urlFields 配列には "key" : "id" を含める必要があります。

  3. actions 配列で、構文 /myEndpoint/{{urlField.myVariable}} を使用してエンドポイントを指定します。myVariable は endpoints 配列で宣言されたエンドポイント変数に対応する urlFields 配列の "key" に指定された値です。

    たとえば、key の値が id の場合、エンドポイント参照は /myEndpoint/{{urlField.id}} になります。

次のスクリーンショットは PokéAPI で /pokemon エンドポイントに追加された /:id 変数を使用して Pokémon を ID で返す例を示しています。

エンドポイント変数

範囲と制限

カスタムコネクタの一部の機能には制限がありますが今後改善される予定です:

  • コネクタごとに 1 つの API のみを使用できます。

  • ステップ

    • トリガはサポートされていません。

    • コネクタの各アクションはターゲット API の 1 つのエンドポイントに対応しています。

  • 認証

    • basic auth、bearer トークン、custom query、および custom body 認証メソッドのみがサポートされています。

      auth_request オブジェクト内で:

      • ユーザ名とパスワードを送信するには、basic_auth を使用します。

      • bearer トークンとして API key を送信するには、bearer を使用します。

      • URL の一部として API key を送信するには、custom_query を使用します。

      • ボディの一部として API key を送信するには、custom_body を使用します。

    • コネクタごとに 1 つの認証メソッドのみを使用できます。

  • カスタムアイコンはサポートされていません。

  • カスタムコネクタは所有者のチームのみ使用できます。

  • カスタムコネクタは更新できません。