アクション
データソース別の設定
gRPC

gRPC

gRPC のデータソースに接続する

1. 右上のメニューから「データソース」を選択する

2. 「データソースの追加」をクリックする

3. データソースの種類の中から「gRPC」を選択する

データソースの選択

4. データソースへの接続に必要な情報を入力して保存する

データソースの接続設定
  1. サービス情報取得のための設定を行なう

ベースマキナは、gRPCメソッドの一覧を取得するためにステップ4で選択したサービス情報の取得先を使用します。

サービス情報の取得先

リフレクションを選択した場合

gRPCサーバーのリフレクションを有効化する必要があります。お手数ですがこちらの例 (opens in a new tab)などをご参考に有効化してください。

Protocol Buffers定義ファイルを選択した場合

gRPCサーバーのリフレクションの有効化は不要です。

代わりに、アクションの設定前にProtocol Buffers定義ファイルをAPI経由でアップロードしていただく必要があります。 詳しい方法についてはProtocol Buffers 定義ファイルの準備をご参照ください。

アップロードが完了すると、データソースの編集ページにて、利用するProtocol Buffers定義ファイルのバージョンを指定できるようになります。

gRPCアクション

共通メタデータを設定する

アクション実行時に自動的に付与される共通メタデータの設定を行なうことができます。

すべてのアクションに同じメタデータの設定を行なう必要があるようなケースでご利用いただけます。

共通メタデータでは、変数・シークレットをご利用いただくことができます。環境に応じて共通メタデータの内容を変えたい場合や、秘匿情報を含めたい場合にご利用ください。

書式については変数・シークレットの使用方法をご覧ください。

共通メタデータの設定フォーム

認証設定

gRPCアクションでは、認証形式として認証用アクションを選択できます。

認証用アクションの設定

認証用アクションを設定すると、アクションの実行前に別のアクションを実行し、その結果を任意のメタデータに設定できます。

例えば、事前にアクセストークンを取得するためのアクションを実行し、結果から取得したトークンを共通のメタデータとして使えます。

認証用アクションの設定フォーム

アクションの実行結果は、メタデータに設定したい文字列を return するJavaScriptコードを記述することで処理します。

このJavaScriptコードの書き方はアクションの結果表示のカスタマイズと共通しているので、アクションの実行ページで事前に動作内容を確認できます。

gRPC をアクションで利用する

1. 右上のメニューから「アクション」を選択する

2. 「アクションの追加」をクリックする

3. アクション名やパラメーターを設定する

データソースの選択
  1. リクエスト方法を登録する

APIに対してのリクエスト内容を入力してください。

この時選べるメソッドの候補には、「gRPCのデータソースに接続する」の5で有効化したServer Reflectionを経由して取得したメソッドの一覧が表示されます。

また、入力できるリクエストボディの値はJSONオブジェクトとして加工できます。

gRPCアクション

Protocol Buffers定義ファイルを選択した場合の設定方法

ファイルをコンパイルする

gRPCアクションでは、リフレクションのかわりにコンパイル済みのProtocol Buffers定義ファイルからメソッドの一覧を取得できます。

例: api.proto

ファイルをコンパイルするには、次のように protoc コマンドに -o オプションと --include_imports オプションを付与して実行してください。

syntax = "proto3";

package api;

service Service {
  rpc Method (Request) returns (Response) {}
}

message Request {}

message Response {
  string message = 1;
}
$ protoc -o out.protoset --include_imports api.proto

protoc によって生成された out.protoset がコンパイル済みProtocol Buffers定義ファイルです。

このファイルをベースマキナへアップロードすることで、リフレクションを使わずにgRPCアクションを実行できます。

ファイルをアップロードする

コンパイル済みProtocol Buffers定義ファイル(以下、protosetファイル)は、API経由でベースマキナにアップロードできます。

アップロードされたprotosetファイルはバージョン管理され、過去にアップロードされたものも使用できます。

デフォルト値は、常に最新のバージョンを利用するに設定されています。

アップロード方法は下記の通りです。

protosetアップロードAPIのURL

下記URLにPOSTメソッドでリクエストを送信してください。

HTTP Header

  • X-Basemachina-Grpc-Api-Access-Token ヘッダーに、gRPC APIアクセストークンを設定してください。

リクエストボディの形式

multipart/form-data形式で、下記の2つを送信してください。

  • params: JSON形式のパラメータ
  • file: protosetファイル

パラメータの形式

下記項目を含んだJSONを指定してください。

  • environmentId(必須)
    • 環境のID。
    • アップロードしたprotosetファイルを使用したい環境のIDを指定してください。
    • gRPCデータソースの編集画面で、サービス情報の取得先Protocol Buffers 定義ファイルを指定すると表示されます。
環境ID
  • resourceId(必須)
    • gRPCデータソースのID。
    • gRPCデータソースの編集画面で、サービス情報の取得先Protocol Buffers 定義ファイルを指定すると表示されます。
データソースID
  • name(任意)
    • protosetファイルのバージョンにつける名前。
    • 指定しなかった場合も、アップロードが行なわれた時間で識別可能です。
protosetファイル名

パラメータの設定例

{
  "environmentId": "ccp9ee76i1ea3prs2f50",
  "resourceId": "c8uo2q7kobjglbr9u6vg",
  "name": "version 1"
}

アップロード例

cURLでアップロードするサンプルを掲載します。 実際に使用する場合は、 {{ }} で囲った箇所を必要な値に置き換えて実行してください。

curl --location --request POST 'https://api.basemachina.com/v1/upload_protoset' \
--header 'X-Basemachina-Grpc-Api-Access-Token: {{ gRPC APIアクセストークン }}' \
--form 'params="{
  \"environmentId\": \"{{ 環境ID }}\",
  \"resourceId\": \"{{ gRPCデータソースID }}\"
}"' \
--form 'file=@"{{ protosetファイルのパス }}"'