メインコンテンツまでスキップ
バージョン: 0.13.0 (Previous)

🏠 住所

住所は、ホストが提供する findAddressDriver をバックエンドとした認証済み日本の郵便番号検索サービスを提供します。

ここから始める​

import {drivers, services} from '@nodeblocks/backend-sdk';

const findAddressDriver = drivers.createJapanPostDriver(
  process.env.JAPAN_POST_CLIENT_ID!,
  process.env.JAPAN_POST_SECRET_KEY!,
);

app.use(
  '/api',
  services.addressService(
    {identities},
    {authSecrets: {authEncSecret: 'replace-me', authSignSecret: 'replace-me'}},
    {findAddressDriver},
  ),
);
設定デフォルト/ソースの動作効果
authSecrets必須；選択された認証ユースルに渡されるアクセストークンの検証を行う。
authMode省略または 'bearer' はBearerトークンを選択'cookie' はCookie認証を選択する。
identity.typeIds提供された場合、設定を通じてそのまま渡される住所ルートでは消費されない。
findAddressCache省略時はキャッシュなし正規化された郵便番号で住所をキャッシュする。
findAddressDriver オプション検索に必須；デフォルトは undefinedfindAddress(postalCode) を提供する。

よくあるタスク​

タスク該当ドキュメントコントラクト
住所を検索するfindAddressFeaturefindAddressFeature と findAddressRoute
Japan Postドライバーを作成するcreateJapanPostDrivercreateJapanPostDriver
住所のリクエスト定義を再利用する住所スキーマ住所スキーマ
検索サービスをマウントするaddressServicefindAddressDriver オプション付きの addressService

Bearer HTTPワークフロー​

authMode を省略するか authMode: 'bearer' に設定した場合、有効なアクセストークンと findAddressSchema が受け付けるクエリ値を送信します：

ADDRESS_API='https://api.example.test'
ACCESS_TOKEN='replace-with-a-valid-access-token'

curl "$ADDRESS_API/addresses?postalCode=100-0001" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

findAddressRoute は、Expressのデフォルト 200 ステータスで住所のJSONオブジェクトを返します。選択されたBearerアダプタは 401 で認証を拒否する可能性があります。存在しない住所は 404 にマッピングされます。ユーザーのアクセストークンのセキュリティチェックは、設定された/デフォルトの認証ユースルによって必要なリクエスト検証データを使用します。

authMode: 'cookie' を設定し、サービスをマウントする前にcookie-parserを登録します。認証サービスによって確立されたアクセストークンのCookieと同じクエリパラメータを送信します：

ADDRESS_API='https://api.example.test'
ACCESS_TOKEN='replace-with-a-valid-access-token'

curl "$ADDRESS_API/addresses?postalCode=100-0001" \
  --cookie "accessToken=$ACCESS_TOKEN"

エンドポイント、リクエストスキーマ、応答、404 の動作は変更されていません。存在しないまたは無効なCookieはCookie認証アダプタによって拒否されます。トークンCookieの設定については認証を参照してください。

カスタム機能合成​

findAddressFeature はスキーマとルートのコンポーザーです。このフラグメントは、addressService なしでマウントするために必要なソース同等のサービスコンテキストを示しています：

import {partial} from 'ramda';
import {features, primitives, utils} from '@nodeblocks/backend-sdk';

const router = primitives.defService(
  partial(primitives.compose(features.findAddressFeature), [
    {
      authenticate: utils.getBearerTokenInfo,
      configuration,
      dataStores: {identities},
      findAddressDriver,
    },
  ]),
);

app.use('/api', router);

このフラグメントは configuration.authSecrets、identities コレクション、および findAddressDriver を必要とします。エンドポイントコントラクトには findAddressRoute と findAddressSchema を使用してください。

リファレンスマップ​

ページ目的
ブロック検索コントラクト、エラー、公開型
機能スキーマからルートへの合成
ルート保護された住所エンドポイント
スキーマ再利用可能な住所データと検索リクエストスキーマ
バリデーター共有の認証要件

住所サービス は、このカテゴリのマウント可能な統合 surface です。

関連モジュール​

Japan Postドライバー が検索実装を提供します。認証 は、この保護されたルートで使用されるトークントランスポートを文書化しています。