コンテンツにスキップ
KARTE Craft Developer Portal

HTTPエンドポイントから実行する（エンドポイント）

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

craft-endpoint

このトリガーを使うことで、ユーザーは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.endpointSuffixURLエンドポイントの末尾の文字列です。
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リクエストを送ります。

Terminal window
## 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_urlString (URL)このフィールドが設定されていた場合は、Craft EndPointはlocationヘッダにその値を設定し、statusを 302 とした上でレスポンスします。下記のcraft_status_code に3系の値を設定した場合は上書きしてレスポンスします。3系以外の値を設定した場合は無視され、 302でレスポンスします。
craft_status_codeNumberこの値が設定されていた場合、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