Craft Endpoint

Suggest Edits

📘
本機能はGrowthプランからご利用いただけます。

Craft Endpoint はFunctionを実行するためのHTTPエンドポイントです。

このトリガーを使うことで、ユーザーはKARTEの機能を介さずに直接Functionを実行できます。

設定手順

[ファンクション詳細画面] の [エンドポイント設定] タブで、 [作成] を選択します。
- 表示されたモーダルで [はい] を選択します。
エンドポイントURLが生成されます。
- URLの右にあるボタンを選択すると、URLをクリップボードにコピーできます。

Craft Functionsに送信されるデータ

data のフォーマットは Function実行時に送信されるデータをご確認ください。

kind は `"karte/track-hook" が入ります。
jsonPayload には以下のフォーマットで値が入ります。

"jsonPayload": {
  "name": "craft-hook",
  "data": {
    "plugin_name": "craft",
    "hook_data": {
      "body": "{ Request Body }",
      "endpointSuffix": "{ Endpoint Suffix }",
      "ip": "{ Source IP Address }",
      "query": {
        "queryKey": "queryValue"
      },
      headers: {
        "origin": "{ Origin }",
        "authorization": "{ Authorization }",
        "user-agent": "{ userAgent }",
        "referer" : "{ Referrer }",
        "content-length": "{ ContentLength }",
        "content-type": "{ ContentType }"
      }
    }
  }
}

Key	説明
`jsonPayload.name`	`"craft-hook"` が入ります。
`jsonPayload.data.plugin_name`	`"craft"` が入ります。
`jsonPayload.data.hook_data.body`	エンドポイントへのリクエスト時の Body が入ります。JSON文字列で送信した場合は Object 型になります。
`jsonPayload.data.hook_data.endpointSuffix`	URLエンドポイントの末尾の文字列です。
`jsonPayload.data.hook_data.ip`	エンドポイントにリクエストを行ったクライアントのIPアドレスです。
`jsonPayload.data.hook_data.query`	リクエスト時のクエリパラメータです。Key-Value形式にパースされます。
`jsonPayload.data.hook_data.headers.origin`	エンドポイントへのリクエスト時のOriginヘッダーの値が入ります。この要素はリクエストにOriginヘッダーが含まれる場合のみ存在します。
`jsonPayload.data.hook_data.headers.authorization`	エンドポイントへのリクエスト時のAuthorizationヘッダーの値が入ります。この要素はリクエストにAuthorizationヘッダーが含まれる場合のみ存在します。
`jsonPayload.data.hook_data.headers.user-agent`	エンドポイントへのリクエスト時のUser Agentヘッダーの値が入ります。この要素はリクエストにUse rAgentヘッダーが含まれる場合のみ存在します。
`jsonPayload.data.hook_data.headers.referrer`	エンドポイントへのリクエスト時のReferrerヘッダーの値が入ります。この要素はリクエストにReferrerヘッダーが含まれる場合のみ存在します。
`jsonPayload.data.hook_data.headers.content-length`	エンドポイントへのリクエスト時のContent Lengthヘッダーの値が入ります。この要素はリクエストにContent Lengthヘッダーが含まれる場合のみ存在します。
`jsonPayload.data.hook_data.headers.content-type`	エンドポイントへのリクエスト時のContent Typeヘッダーの値が入ります。この要素はリクエストにContent Typeヘッダーが含まれる場合のみ存在します。

ファンクションの実行方法

URLエンドポイントにPOST あるいはGETリクエストを送ります。

## Curlによる実行例
curl --location --request POST 'https://t.karte.test/hook/mock/craft/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "test": 1
}'

正常なリクエストを受信した場合、Craft Functionsは「Craft Functionsに送信されるデータ」に記載のフォーマットで data を受け取ります。

// data の例 (JSON表記)
{
  "id": "3a118b29-c131-49af-95db-6006b00896ad",
  "kind": "karte/track-hook",
  "timestamp": "2023-01-1_1T06:28:26.490Z",
  "jsonPayload": {
    "name": "craft-hook",
    "data": {
      "plugin_name": "craft",
      "hook_data": {
        "body": {
          "test": 1
        },
        "endpointSuffix": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "ip": "1.1.1.1"
      }
    }
  }
}

hookが成功すれば、エンドポイントは200のステータスを返却します。このとき Craft Functions の関数内でreturnした値をResponse Bodyとして返却します。

URLが無効な場合（非アクティブ、削除済みなど）は404ステータスを返却します。

エンドポイントへのリクエストがタイムアウトした場合は502ステータスを返却します。

特別なレスポンス

Craft FunctionsでObject型かつ下記のフィールドを設定した際は、特別なレスポンスを返します。

フィールド名	型	挙動
`craft_redirect_url`	String (URL)	このフィールドが設定されていた場合は、Craft EndPointはlocationヘッダにその値を設定し、statusを 302 とした上でレスポンスします。下記のcraft_status_code に3系の値を設定した場合は上書きしてレスポンスします。3系以外の値を設定した場合は無視され、 302でレスポンスします。
`craft_status_code`	Number	この値が設定されていた場合、Craft Endpointはstatusにその値を設定した上でレスポンスします。上記のcraft_redirect_urlが設定されていた場合はそちらの挙動が優先されます。

オリジン管理リソース共有 (CORS) への対応状況

Craft EndpointはKARTE接客アクションからのリクエストを想定して、オリジン間リソース共有に対応しています。具体的には、クライアントからのプリフライトリクエストに対して以下のヘッダーを返却します。

Access-Control-Allow-Origin: (リクエストのOriginヘッダーの値)
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type
Access-Control-Allow-Credentials: true

Updated 9 months ago

What’s Next

Craft Functionsのトリガー