API Gateway タイプトリガー

Prev Next

Classic環境で利用できます。

NAVERクラウドプラットフォームコンソールの Cloud Functions > Action > アクション詳細情報 で API Gatewayタイプのトリガーを追加できます。API Gatewayは、APIの呼び出し、管理、モニタリングなど、APIに関連するすべてのタスクを実行できるサービスです。

参考

API Gatewayの利用時には、別途料金が発生します。API Gatewayの紹介と料金プランについての説明は、NAVERクラウドプラットフォームポータルの サービス > Application Services > API Gateway メニューをご参照ください。

トリガー追加

API Gatewayタイプのトリガーを追加するには、トリガータイプで API Gatewayをクリックして選択し、API Gatewayの接続情報を設定する必要があります。

cloudfunctions-apigateway-vpc_v2_01_ko

トリガータイプ

API Gatewayのトリガータイプは、接続したいアクションタイプによって異なります。ウェブアクションまたはシーケンスウェブアクションを接続する場合、HTTP方式の API Gatewayトリガーが作成されます。一方、一般アクションやシーケンスアクションを接続する場合は、Webhook方式の API Gatewayトリガーが作成されます。各方式についての説明は、次の通りです:

HTTP方式

  • HTTPリクエスト/レスポンスを直接処理する方式で REST APIを実装できます。
  • POST、GET、OPTIONS、PUT、DELETE、PATCH、HEADメソッドをサポートします。
  • HTTPのリクエストヘッダ、パラメータ、パス、ボディの値をアクションに渡します。
  • アクションコードで定義したステータスコード、ヘッダ、ボディを HTTPレスポンスで受け取ることができます。

Webhook方式

  • HTTPリクエストでアクションを実行できます。
  • POSTメソッドをサポートします。
  • アクションコードでリターンする同期方式(request and reply)と、アクションの実行する非同期方式(fire and forget)をサポートします。詳細な説明は、クエリパラメータをご参照ください。

API Gateway設定

アクションを実行するための API Gatewayエンドポイントを設定します。詳細な API Gatewayの設定は、API Gateway ご利用ガイドをご参照ください。

Product

  • 複数の APIを管理するための単位として、それぞれの Productごとに呼び出しドメインを提供します。

API

  • API明細と Overviewを管理する単位として、関連するリソースとメソッドを定義して認証方式を設定できます。

Resource

  • APIの URLパス(エンドポイント)を設定できます。
  • HTTPタイプは、リソースの値を {type+}に指定すると、呼び出された下位リソースを含むパスをアクションコードで参照することができます。
  • 選択したリソースの下位にサポートするメソッドと同じメソッドが既に存在する場合は選択できません。

Stage

  • APIリリース単位として開発、テスト、運用、またはバージョンコード(v 0.0.1)のような形式で作成、運用することができます。
  • 既存の API Gatewayリリース Stageを選択するか、新規作成できます。

API Key認証

  • API Key認証を有効にすると、ユーザーの API Keyを使用して APIを呼び出すことができます。

認証

  • APIを保護するために、NAVERクラウドプラットフォームが提供する IAM認証を使用します。
    • NONE: 認証を使用しない
    • IAM: NAVERクラウドプラットフォームが提供する IAM認証を使用
    • IAM + AUTHORIZATION: NAVERクラウドプラットフォームが提供する IAMを通じたユーザー認証と Method単位の権限認可機能を使用

トリガー実行

エンドポイント

アクションを実行できる API Gatewayトリガーの実行エンドポイントは、以下のような形式で作成されます。

https://{product_id}.apigw.ntruss.com/{api_name}/{stage_name}/{resource_name}

HTTPリクエスト

リクエストメソッド

HTTP方式

  • すべての POST、GET、OPTIONS、PUT、DELETE、PATCH、HEADメソッドをサポートします。

Webhook方式

  • POSTメソッドをサポートします。

リクエストヘッダ

HTTP方式

  • すべてのコンテンツタイプを許可し、アクションコードでリクエストヘッダを参照できます。

Webhook方式

  • application/jsonコンテンツタイプのみ許可します。

クエリパラメータ

HTTP方式

  • クエリパラメータ値をアクションコードに渡して、コードでパラメータ値を使用できます。
  • クエリパラメータを参照するためには、接続されたアクションの HTTPソース使用 の設定を有効にしてください。

Webhook方式

  • アクションコードでクエリパラメータの値を参照できません。
  • 実行時に下記のクエリパラメータを使用して、API呼び出しの処理方法と結果値を調整できます。
  • blocking
    • true
      • 同期(request and reply)リクエスト。
      • アクションの実行が完了した後に HTTPレスポンスを受け取ることができ、アクションの実行結果がレスポンスボディの値として渡されます。
      • アクションの実行が1分を超えると、非同期呼び出しに切り替わります。
    • false
      • 非同期(fire and forget)リクエスト。デフォルト値。
      • アクション実行の成功/失敗の有無に関係なく HTTPレスポンスを直接渡し、レスポンスボディにはアクション実行履歴 ID(アクティベーション ID)の値のみ渡します。
  • result
    • true
      • アクションコードのリターン値を HTTPレスポンスボディに渡します。
    • false

リクエストボディ

HTTP方式

  • application/jsonコンテンツタイプは、Cloud Functionsシステムコントローラで自動的に変換し、アクションパラメータに Key/Value形式で渡します。
  • その他のコンテンツタイプを処理するためには、接続されたアクションの HTTPソース使用 の設定を有効にしてください。
  • テキストコンテンツタイプはプレーンテキスト形式でアクションに渡され、バイナリタイプは Base64でエンコードされて渡されます。

Webhook方式

  • リクエストボディの JSONデータをアクションランタイムパラメータとして渡されます。

アクションに渡されるイベント

HTTPリクエストイベントデータは、アクションランタイムパラメータとして渡されます。

HTTP方式

{
    "__ow_headers": {
        "content-type": "application/json"
    },
    "__ow_method": "post",
    "__ow_path": "/",
    "__ow_query": "key1=value1&key2=value2",
    "__ow_body": "eyJhIjogImIiLCAiYyI6IDF9",
}

Webhook方式

{
    "name": "Cloud Functions"
}

HTTPレスポンス

HTTP方式

HTTP方式はアクションのリターン値からヘッダ、ボディ、ステータスコードを JSON形式で定義できます。Cloud Functionsシステムコントローラがこれを HTTPレスポンス形式に変換します。

  • headers: キーがヘッダ名であり、文字列、数値、または boolean値で構成されている jsonオブジェクト。
  • statusCode: HTTPステータスコード。デフォルト値は 200 OK。bodyが null、空文字列("")、undefinedの場合は、204 No Contentで処理されます。
  • body: プレーンテキスト、JSONオブジェクト、配列文字列、base64でエンコードされたバイナリデータなどのレスポンスボディを定義します。デフォルト値は空白のレスポンス。
// Content-Type: JSON
{
    statusCode: 200,
    headers: {
        "Content-Type": "application/json"
    },
    body: {"key":"value"}
}

// Content-Type: HTML 
{
    "statusCode": 200,
    "headers": {
        "Content-Type": "text/html"
    },
    "body": "<html><body><h3>hello</h3></body></html>" }
}

// Content-Type: TEXT 
{
    "statusCode": 200,
    "headers": {
        "Content-Type": "text/plain"
    },
    "body": "hello" }
}

// Content-Type: Image 
{
    "statusCode": 200,
    "headers": {
        "Content-Type": "image/png"
    },
    "body": "<base64 encoded string>" }
}

// HTTP Redirect
{
    "statusCode": 302,
    "headers": { 
        "location": "https://www.ncloud.com"
    }
}

// ヘッダ Cookieの設定
{
    "statusCode": 302,
    "headers": { 
        "Set-Cookie": "UserID=Jane; Max-Age=3600; Version=",
        "Content-Type": "text/html"
    },
    "body": "<html><body><h3>hello</h3></body></html>"
}
参考

OPTIONSリクエストは基本的に Corsヘッダがレスポンスヘッダに自動追加されます。これらのヘッダはすべての Originを許可し、OPTIONS、GET、DELETE、POST、PUT、HEAD、PATCHメソッドを許可します。さらに、HTTPリクエストが存在する場合、Access-Control-Request-Headersヘッダは Access-Control-Allow-Headersヘッダにエコーバックされます。作成されるデフォルト値は次の通りです。

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: OPTIONS, GET, DELETE, POST, PUT, HEAD, PATCH
Access-Control-Allow-Headers: Authorization, Content-Type

OPTIONSリクエストは、ウェブアクションによって手動で処理することもできます。手動処理のためには、 ヘッダオプション設定 を有効にしてください。CORSヘッダはこれ以上自動的に追加されず、アクションコードで直接定義する必要があります。

注意
  • HTTP方式は最大1分までのレスポンスを受け取ることができます。アクションが1分以上実行されると、202 Acceptedレスポンスを受け取ります。ボディには以下のようなエラーが含まれます。
{
    "code": "fe398a568d89a5efbeaedbb5bc415cbb",
    "error": "Response not yet ready."
}
  • アクションが返すことができる最大レスポンスサイズがあるため、最大サイズを超えるレスポンス値を返そうとすると、アクションの実行結果は失敗として処理されます。画像のようなオブジェクトファイルを返す場合は最大レスポンスサイズに注意し、最大サイズを超える場合はアクションコードで返さずに他のストレージを利用してください。最大レスポンスサイズの仕様については、Cloud Functions の仕様をご参照ください。

Webhook方式

Webhook方式はボディのみ定義できます。

  • ステータスコード: 同期方式は 200 OK。非同期方式は 202 Accepted
  • body: 同期方式はアクションコードからのリターン値。非同期方式はアクション実行履歴 ID
注意

同期方式で実行する場合、アクションが1分以上実行されると非同期方式に切り替わります。

実行例

HTTP方式

  • アクションリターン値
{
    "statusCode": 200,
    "headers": {
            "Custom-Header": "custom value"
            "Content-Type": "application/json"
        },
    "body": {"name": "Cloud Functions"}
}
  • 実行
$ curl -i -X GET "https://myproduct.apigw.ntruss.com/api/v1/users" 

HTTP/2 200
content-type: application/json
custom-header: custom value
x-request-id: c64b4dc037c7be7bbe73213beacff8eb
x-ncp-apigw-response-origin: ENDPOINT

{
    "name": "Cloud Functions"
}

Webhook方式

  • アクションリターン値
{
    "name": "Cloud Functions"
}
  • 実行(同期)
$ curl -i -X POST -H "Content-Type: application/json" "https://myproduct.apigw.ntruss.com/api/v1/action?blocking=true&result=true -d '{"key1": "value1"}'


HTTP/2 200
content-type: application/json
x-request-id: c64b4dc037c7be7bbe73213beacff8eb
x-ncp-apigw-response-origin: ENDPOINT

{"name":"Cloud Functions"}
  • 実行(非同期)
$ curl -i -X POST -H "Content-Type: application/json" "https://myproduct.apigw.ntruss.com/api/v1/action?blocking=false -d '{"key1": "value1"}'

HTTP/2 202
content-type: application/json
x-request-id: c64b4dc037c7be7bbe73213beacff8eb
x-ncp-apigw-response-origin: ENDPOINT

{"activationId":"e04d1a62a3e14eb58d1a62a3e18eb590"}
事業者登録番号: 129-86-31394 通信販売業申告番号:第2009-京畿城南-0510号
代表取締役: キム・ユウォン アドレス: 13561 京畿道 城南市 盆唐区 仏亭路6 グリーンファクトリー, 17~26F お客様センターの代表電話: 1544-5876
© NAVER Cloud Corp. All Rights Reserved.