環境変数
環境変数を使用すると、コードを変更せずに環境内で実行されているアプリケーションプロセスに変数を追加できます。環境変数は安全に保存され、次のようなユースケースに最適です。
- サードパーティ統合用の API キー
- アプリケーションロジックの機能フラグ
- 環境間で異なる構成、またはシークレットではない可能性がある構成
環境変数は、アプリケーションサーバーでのみアクセスできます。環境変数によって、プロキシやエッジ関数を含むエッジサービスの動作を変更することはできません。
このチュートリアルに従って環境変数を設定し、次にコードを PWA Kit サイトに実装してその変数を使用します。特定の要件に応じてコードをカスタマイズできます。このチュートリアルでは、次の方法について説明します。
変更を本番環境にデプロイする前に、ローカルマシンで手順をテストし、次に非本番環境でテストすることをお勧めします。詳細については、ベストプラクティス、環境変数のトラブルシューティング、およびローカルでのデバッグを参照してください。
環境変数は:
- Managed Runtime API または Runtime Admin を使用して管理できます。
process.env
を使用して Node.js でアクセスします。
新しい環境変数を導入する場合は、まず API または Runtime Admin で設定します。再デプロイが完了するまで待ってから、その環境変数を使用する新しいバンドルをデプロイします。
環境変数の設定、更新、および設定解除
projects_target_env_var_partial_update を使用します。
既存の環境変数の設定を解除するには、その値を null
に設定します。
環境変数を変更すると、環境が再デプロイされます。更新された値は、デプロイの完了時に使用可能になります。
すべての環境変数の取得
projects_target_env_var_list を使用します。
環境変数を作成、更新、削除、または表示するには、以下の手順に従います。
- Runtime Admin にログインします。Runtime Admin にアクセスするには、Managed Runtime の管理を参照してください。
- プロジェクトの Overview (概要) ページを開きます。
- 環境変数を管理する環境の名前をクリックします。
- 左側のナビゲーションでEnvironment Variables (環境変数) をクリックします。
- アプリにとって意味のある環境変数名を選択してください。わかりやすい名前を使用します。環境変数には明確で簡潔な名前を選択して、チームが簡単に理解できるようにします。
- API キーなどの機密情報をコードにハードコーディングすることは避けてください。環境変数を使用して安全を確保します。
- ページにシリアル化されるデータに環境変数を渡さないでください。環境変数データが漏洩していないことを確認するために、テストを追加することを検討してください。
getProps
や react-query フックから環境変数を返さないでください。- 環境変数はサーバー側でのみ使用します。デフォルトでは、環境変数はクライアント側で公開されません。クライアント側 (構成ファイルなど) で値を公開することもできますが、値の公開がセキュリティプラクティスに準拠していることを確認してください。
- 環境変数をローカルマシンでテストし、次に非本番環境でテストしてから、本番環境にデプロイしてください。これにより、本番環境にデプロイする前に問題をローカルで迅速に解決できるほか、サイトの動作をシミュレートし、機能を検証し、ユーザー受け入れテストを行うことができます。
- 環境変数が定義されていないことによるエラーを防ぐために、環境変数を使用するコードにエラーハンドリングを含めます。
- 環境変数へのアクセスを制御して、不正な変更を防止します。
- 各環境変数の目的と構成を文書化します。これは、新しいデベロッパーのオンボーディングと問題のトラブルシューティングに役立ちます。
環境変数の使用には、次のような制約があります。
- 環境変数の値は文字列でなければなりません。複雑な値を格納するには、JSON を文字列にエンコードします。
- 各環境には 100 までの環境変数の制限があります。
- 環境に設定される環境変数の値の最大サイズは 32 KB です。
- 環境変数名は 512 文字以下である必要があり、予約された接頭辞 (
AWS
、MRT
、X_MRT
、MOBIFY
、X_MOBIFY
、SSR_PROXY
、NODE
) で始めることはできません。 - 予約された名前 (
BUNDLE_ID
、DEPLOY_ID
、DEPLOY_TARGET
、EXTERNAL_DOMAIN_NAME
、HANDLER
、LAMBDA_RUNTIME_DIR
、LAMBDA_TASK_ROOT
、NODE_ENV
、REDIRECT_BUCKET
、REDIRECT_KEY
、REDIRECT_UPDATE
、REMOTE
、X_AMZN_TRACE_ID
) は、環境変数名には使用できません。
このセクションでは、環境変数の使用中に発生する可能性のある一般的なエラーに対して推奨される解決策を示します。
コードは、変数が見つからないことを示す Error
をスローします。
原因: コードが呼び出す環境変数が設定されていません。
推奨される解決策: projects_target_env_var_partial_update API エンドポイントを呼び出して、該当する環境変数を設定します。
コードは、環境変数が見つからなかったことを示すエラーメッセージをログに記録します。
原因: コードに入力ミスがあるか、正しくない環境変数名が使用されているため、コードで環境変数が見つかりませんでした。
推奨される解決策: コードで環境変数名のスペルが正しいこと、および目的の環境変数名を使用していることを確認します。projects_target_env_var_list API エンドポイントを呼び出して環境変数名をチェックし、設定されている変数の完全なリストを確認します。
環境変数を設定するための API 呼び出しが失敗します。
原因: 環境変数名が制約に準拠していない可能性があります。たとえば、環境変数の値のサイズが 32 KB を超えている場合などです。
推奨される解決策: 環境変数が制約に準拠していることを確認します。
認証エラーは、API キーの使用を含むコードを実行するときに発生します。
原因: 環境変数の設定時に使用した API キーが、予期される形式ではないか、欠落しています。
推奨される解決策: 環境変数で格納されている API キーが正しいことを確認します。必要に応じて、projects_target_env_var_partial_update API エンドポイントを呼び出して API キーを修正します。
fetch
リクエストはネットワークエラーで失敗します。
原因: コードで呼び出された API エンドポイントの URL が正しく定義されていないか、無効である可能性があります。たとえば、コンテンツ管理システム (CMS) エンドポイントの URL が正しくない場合などです。
推奨される解決策: コード内の API エンドポイントの URL が正しいことを確認します。