SaaS Proxy でプロバイダー API を呼び出す

Connector の操作として用意されていないエンドポイントには SaaS Proxy を使えます。バックエンドがパス、メソッド、パラメーターを指定し、Connector がユーザーの接続済みアカウントを選択して認証情報を付加します。プロバイダーの proxy 対応と、アカウントの必要な権限が前提です。

接続済みアカウントの準備

先に Connector for SaaS ガイドを完了してください。Project API key はバックエンドに保管し、検証済みのユーザーとアカウントの対応を保存します。oo_proj_… 形式の Project key を使い、個人キーやプロバイダーの token は使いません。userId とアカウントはログイン済みセッションから決定し、ブラウザーからの任意のアカウント ID を信用しないでください。

HTTP で呼び出す

POST https://connector.oomol.com/v1/saas/proxy/{service}
Authorization: Bearer <project-api-key>
Content-Type: application/json

次の Gmail 読み取り例は接続済みアカウントのプロフィールを取得します。設定 ID とアカウント ID を保存済みの値に置き換え、プロフィールの読み取り権限を確認してください。外側の HTTP メソッドは常に POST で、上流のメソッドは request 内に指定します。

export PROJECT_API_KEY='oo_proj_...'
export PROVIDER_CONFIG_ID='<gmail-provider-config-id>'
export CONNECTED_ACCOUNT_ID='<connected-account-id>'

curl --silent --show-error \
  'https://connector.oomol.com/v1/saas/proxy/gmail' \
  -H "Authorization: Bearer $PROJECT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'x-request-id: req-saas-proxy-1' \
  --data @- <<JSON
{
  "providerConfigId": "$PROVIDER_CONFIG_ID",
  "userId": "customer-1",
  "connectedAccountId": "$CONNECTED_ACCOUNT_ID",
  "request": {
    "endpoint": "/users/me/profile",
    "method": "GET"
  }
}
JSON

リクエストフィールド

フィールド	用途
`userId`	必須。接続済みアカウントに対応する自社製品のユーザー ID。
`providerConfigId`	任意ですが指定を推奨。URL のサービスと一致する設定 ID。省略する場合、そのサービスの有効な設定がプロジェクト内に一つだけ必要です。
`connectedAccountId` / `alias`	任意。どちらか一つまで指定できます。両方を省略すると、そのユーザーと設定に属する最新の active アカウントが選択されます。
`request.endpoint`	必須。/ で始まりプロバイダーの Base URL に追加されるパス、または許可されたオリジンの HTTPS URL。Gmail の Base URL は https://gmail.googleapis.com/gmail/v1 です。
`request.method`	必須。GET、POST、PUT、PATCH、DELETE のいずれか。
`request.query`	任意。値は文字列、数値、真偽値、null。null は省略され、配列や入れ子のオブジェクトは使用できません。
`request.headers`	任意。認証以外のヘッダー。認証情報は Connector が付加するため、Authorization、Cookie、Host、X-API-Key は指定しません。
`request.body`	任意。上流への書き込みに使う JSON またはテキスト。GET では本文を送信しません。

ProjectConnector で呼び出す

ProjectConnector.proxy を含む @oomol-lab/connector のリリースを使用してください。インストール済みの版にこのメソッドがない場合は HTTP の例を使えます。SDK の externalUserId と connectionName は userId と alias に変換されます。connectedAccountId が connectionName より優先されます。型引数は期待する型を表し、実行時のデータ検証は行いません。

npm install @oomol-lab/connector

import { ProjectConnector } from "@oomol-lab/connector";

const project = new ProjectConnector({
  apiKey: process.env.PROJECT_API_KEY!,
});

const result = await project.proxy<{ emailAddress: string }>(
  "customer-1",
  "gmail",
  { endpoint: "/users/me/profile", method: "GET" },
  {
    providerConfigId: process.env.PROVIDER_CONFIG_ID!,
    connectedAccountId: process.env.CONNECTED_ACCOUNT_ID!,
    retries: 0,
  },
);

if (result.status < 200 || result.status >= 300) {
  throw new Error(`Provider returned HTTP ${result.status}`);
}
console.log(result.data.emailAddress);

同じユーザーで複数回呼び出す場合は、ユーザーを一度だけ指定できます：

const user = project.forUser("customer-1");
const profile = await user.proxy<{ emailAddress: string }>(
  "gmail",
  { endpoint: "/users/me/profile", method: "GET" },
  {
    providerConfigId: process.env.PROVIDER_CONFIG_ID!,
    connectionName: "work",
    retries: 0,
  },
);
if (profile.status < 200 || profile.status >= 300) {
  throw new Error(`Provider returned HTTP ${profile.status}`);
}
console.log(profile.data.emailAddress);

レスポンスとエラーの処理

以下は HTTP レスポンスの構造例です。SDK は data 内の status、headers、data を直接返します。HTTP 呼び出しでは meta.executionId を保存して調査に使えます。

{
  "success": true,
  "message": "OK",
  "data": {
    "status": 200,
    "headers": { "content-type": "application/json" },
    "data": {
      "emailAddress": "user@example.com",
      "messagesTotal": 120,
      "threadsTotal": 80,
      "historyId": "12345"
    }
  },
  "meta": {
    "executionId": "exec-example",
    "service": "gmail",
    "appId": "app-example"
  }
}

両方の結果を確認してください。Connector が成功しても data.status が上流の非 2xx になることがあります。SDK では result.status とプロバイダーの本文を確認します。Connector の失敗は ConnectorError になります。無効な Project API key は HTTP 401 とプレーンテキスト Unauthorized を返す場合があるため、すべてのエラーが JSON とは限りません。

制限とトラブルシューティング

Proxy は解析済み JSON またはテキストを返し、ストリーミングやバイナリ転送用ではありません。既定の上流タイムアウトは 30 秒、レスポンス上限は 4 MiB です。プロバイダーが個別に変更する場合があります。
Proxy は OAuth 権限を追加しません。scope 不足の場合は設定を確認し、必要な権限でユーザーに再認証してもらいます。許可されたプロバイダーのオリジンだけが対象です。
provider_config_not_found と multiple_provider_configs_found は設定選択、proxy_not_supported は非対応プロバイダーを示します。proxy_upstream_timeout や proxy_response_too_large の場合は、可能なら取得範囲を小さくします。
タイムアウトしても上流への書き込みが失敗したとは限りません。重複を避ける必要がある操作では自動再試行を無効にします。SDK の例は retries をゼロにしています。リクエスト ID と、返された場合は HTTP の meta.executionId を記録し、OOMOL Console のプロジェクト実行ログを確認します。

ProjectConnector によるアカウント接続も参照してください。