UpdateServer - AWS Transfer Family
リクエストの構文リクエストパラメータレスポンスの構文レスポンス要素エラー例その他の参照資料

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

UpdateServer

ファイル転送プロトコル対応サーバーの作成後にそのサーバーのプロパティを更新します。

UpdateServer コールは更新されたサーバーの ServerId を返します。

リクエストの構文

{
   "Certificate": "string",
   "EndpointDetails": { 
      "AddressAllocationIds": [ "string" ],
      "SecurityGroupIds": [ "string" ],
      "SubnetIds": [ "string" ],
      "VpcEndpointId": "string",
      "VpcId": "string"
   },
   "EndpointType": "string",
   "HostKey": "string",
   "IdentityProviderDetails": { 
      "DirectoryId": "string",
      "Function": "string",
      "InvocationRole": "string",
      "SftpAuthenticationMethods": "string",
      "Url": "string"
   },
   "LoggingRole": "string",
   "PostAuthenticationLoginBanner": "string",
   "PreAuthenticationLoginBanner": "string",
   "ProtocolDetails": { 
      "As2Transports": [ "string" ],
      "PassiveIp": "string",
      "SetStatOption": "string",
      "TlsSessionResumptionMode": "string"
   },
   "Protocols": [ "string" ],
   "S3StorageOptions": { 
      "DirectoryListingOptimization": "string"
   },
   "SecurityPolicyName": "string",
   "ServerId": "string",
   "StructuredLogDestinations": [ "string" ],
   "WorkflowDetails": { 
      "OnPartialUpload": [ 
         { 
            "ExecutionRole": "string",
            "WorkflowId": "string"
         }
      ],
      "OnUpload": [ 
         { 
            "ExecutionRole": "string",
            "WorkflowId": "string"
         }
      ]
   }
}

リクエストパラメータ

すべてのアクションに共通のパラメータの詳細については、「共通パラメータ」を参照してください。

リクエストは以下の JSON 形式のデータを受け入れます。

Certificate

AWS Certificate Manager (ACM) 証明書の Amazon リソースネーム (ARN)。Protocols が FTPS に設定されている場合は必須です。

新しいパブリック証明書をリクエストするには、 AWS Certificate Manager ユーザーガイドの「パブリック証明書のリクエスト」を参照してください。

既存の証明書を ACM にインポートするには、 AWS Certificate Manager ユーザーガイドの「ACM への証明書のインポート」を参照してください。

プライベート IP アドレス経由で FTPS を使用できるようにプライベート証明書をリクエストするには、 AWS Certificate Manager ユーザーガイドの「プライベート証明書をリクエストする」を参照してください。

以下の暗号化アルゴリズムとキーサイズの証明書がサポートされています。

  • 2048 ビット RSA (RSA_2048)

  • 4096 ビット RSA (RSA_4096)

  • 楕円素数曲線 256 ビット (EC_Prime256v1)

  • 楕円素数曲線 384 ビット (EC_secp384R1)

  • 楕円素数曲線 521 ビット (EC_secp521R1)

注記

証明書は、FQDN または IP アドレスが指定され、発行者に関する情報が記載された有効な SSL/TLS X.509 バージョン 3 の証明書である必要があります。

型: 文字列

長さの制限: 最小長は 0 です。最大長は 1600 です。

必須: いいえ

EndpointDetails

サーバーに設定された Virtual Private Cloud (VPC) エンドポイント設定。VPC 内でエンドポイントをホストする場合、VPC 内のリソースにのみアクセスできるようにすることも、Elastic IP アドレスをアタッチしてインターネット経由でクライアントにアクセスできるようにすることもできます。VPC のデフォルトのセキュリティグループは、エンドポイントに自動的に割り当てられます。

型: EndpointDetails オブジェクト

必須: いいえ

EndpointType

サーバーで使用したいエンドポイントのタイプ。サーバーのエンドポイントをパブリックアクセス (PUBLIC) にするか、VPC 内でホストするかを選択できます。VPC でホストされているエンドポイントを使用すると、サーバーとリソースへのアクセスを VPC 内のみに制限したり、Elastic IP アドレスを直接アタッチしてインターネット向けにするといった選択ができます。

注記

2021 年 5 月 19 日以降、 AWS 2021 年 5 月 19 日より前にアカウントEndpointType=VPC_ENDPOINTで を使用してサーバーを作成していない場合、そのサーバーを作成することはできません。2021 年 5 月 19 日 AWS以前にアカウントに EndpointType=VPC_ENDPOINTで既にサーバーを作成している場合、影響を受けません。この日付を過ぎたら EndpointType=VPC を使用します。

詳細については、「VPC_ENDPOINT のサポート終了」を参照してください。

VPC を EndpointType として使用することをお勧めします。このエンドポイントタイプでは、最大 3 つの Elastic IPv4 アドレス (BYO IP を含む) をサーバーのエンドポイントに直接関連付けて、VPC セキュリティグループを使用してクライアントのパブリック IP アドレスでトラフィックを制限できます。EndpointType を VPC_ENDPOINT に設定した場合、これは不可能です。

型: 文字列

有効な値：PUBLIC | VPC | VPC_ENDPOINT

必須：いいえ

HostKey

SFTP 対応サーバーで使用する RSA、ECDSA、または ED25519 プライベートキー。キーをローテーションしたい場合や、異なるアルゴリズムを使用するアクティブキーのセットが必要な場合に備えて、複数のホストキーを追加できます。

パスフレーズなしで RSA 2048 ビットキーを生成するには、以下のコマンドを使用する：

ssh-keygen -t rsa -b 2048 -N "" -m PEM -f my-new-server-key.

-b オプションには最小値 2048 を使用してください。3072 または 4096 を使用すると、より強力なキーを作成できます。

パスフレーズなしで ECDSA 256 ビット鍵を生成するには、以下のコマンドを使用する：

ssh-keygen -t ecdsa -b 256 -N "" -m PEM -f my-new-server-key.

ECDSA の -b オプションの有効値は 256、384、521 です。

パスフレーズなしで ED25519 鍵を生成するには、以下のコマンドを使用する：

ssh-keygen -t ed25519 -N "" -f my-new-server-key.

これらのコマンドのすべてについて、 を任意の文字列my-new-server-keyに置き換えることができます。

重要

既存のユーザーを既存のSFTP 対応サーバーから新しいサーバーに移行する計画がない場合、ホストキーを更新しないでください。サーバーのホストキーを誤って変更することは、破壊的な操作になり得えます。

詳細については、「 ユーザーガイド」の「SFTP 対応サーバーのホストキーの更新 AWS Transfer Family 」を参照してください。

型: 文字列

長さの制限: 最小長は 0 です。最大長は 4,096 です。

必須: いいえ

IdentityProviderDetails

カスタマーの認証 API メソッドを呼び出す際に必要なすべての情報を含む配列。

型: IdentityProviderDetails オブジェクト

必須: いいえ

LoggingRole

サーバーが Amazon S3 または Amazon EFSevents の Amazon CloudWatch ログ記録をオンにできるようにする AWS Identity and Access Management (IAM) ロールの Amazon リソースネーム (ARN)。設定すると、 CloudWatch ログにユーザーアクティビティを表示できます。

型: 文字列

長さの制限: 最小長は 0 です。最大長は 2,048 です。

パターン: (|arn:.*role/\S+)

必須: いいえ

PostAuthenticationLoginBanner

ユーザーがサーバーに接続するときに表示する文字列を指定します。この文字列はユーザーが認証した後で表示されます。

注記

SFTP プロトコルは認証後の表示バナーをサポートしていません。

型: 文字列

長さの制限: 最小長は 0 です。最大長は 4096 です。

パターン: [\x09-\x0D\x20-\x7E]*

必須: いいえ

PreAuthenticationLoginBanner

ユーザーがサーバーに接続するときに表示する文字列を指定します。この文字列はユーザーが認証される前に表示されます。例えば、次のバナーはシステムの使用に関する詳細を表示します。

This system is for the use of authorized users only. Individuals using this computer system without authority, or in excess of their authority, are subject to having all of their activities on this system monitored and recorded by system personnel.

型: 文字列

長さの制限: 最小長は 0 です。最大長は 4096 です。

パターン: [\x09-\x0D\x20-\x7E]*

必須: いいえ

ProtocolDetails

サーバー用に構成されたプロトコル設定。

  • パッシブモード (FTP および FTPS プロトコル用) を示すには、PassiveIp パラメータを使用します。ファイアウォール、ルーター、ロードバランサーの外部 IP アドレスなど、クアッドドット形式の単一 IPv4 アドレスを入力します。

  • S3 バケットにアップロードしているファイルに対して、クライアントが SETSTAT コマンドの使用を試みた時に発生するエラーを無視するには、SetStatOption パラメータを使用します。SFTP クライアントを変更せずに AWS Transfer Family サーバーでSETSTATコマンドを無視してファイルをアップロードするには、値を に設定しますENABLE_NO_OP。SetStatOption パラメータを に設定するとENABLE_NO_OP、Transfer Family は Amazon CloudWatch Logs にログエントリを生成し、クライアントがいつSETSTAT呼び出しを行っているかを判断できるようにします。

  • AWS Transfer Family サーバーが一意のセッション ID を介して最近ネゴシエートされたセッションを再開するかどうかを確認するには、 TlsSessionResumptionModeパラメータを使用します。

  • As2Transports は、AS2 メッセージの転送方法を示します。現在は、HTTP のみがサポートされます。

タイプ：ProtocolDetails オブジェクト

必須: いいえ

Protocols

ファイル転送プロトコルクライアントがサーバーのエンドポイントに接続できる 1 つまたは複数のファイル転送プロトコルを指定します。使用可能なプロトコルは次のとおりです。

  • SFTP(Secure Shell (SSH) File Transfer Protocol): SSH 経由のファイル転送

  • FTPS (File Transfer Protocol Secure): TLS 暗号化によるファイル転送

  • FTP (File Transfer Protocol): 暗号化されていないファイル転送

  • AS2 (適用性ステートメント 2): 構造化 business-to-business データの転送に使用されます

注記

  • を選択した場合はFTPS、 AWS Certificate Manager (ACM) に保存されている証明書を選択する必要があります。この証明書は、クライアントが FTPS 経由でサーバーに接続するときにサーバーを識別するために使用されます。

  • Protocol に FTP または FTPS が含まれる場合、EndpointType は VPC でなければならず、IdentityProviderType は AWS_DIRECTORY_SERVICE、AWS_LAMBDA または API_GATEWAY でなければなりません。

  • Protocol に FTPが含まれる場合、AddressAllocationIds は関連付けられません。

  • Protocol が SFTP のみに設定されている場合、EndpointType は PUBLIC に設定でき、IdentityProviderType はサポートされている ID タイプ (SERVICE_MANAGED、AWS_DIRECTORY_SERVICE、AWS_LAMBDA、または API_GATEWAY) のいずれかに設定できます。

  • Protocol が AS2 を含む場合、EndpointType は VPC でなければならず、ドメインは、Amazon S3 でなければなりません。

タイプ：文字列の配列

配列メンバー：最小数は 1 項目です。最大数は 4 項目です。

有効な値：SFTP | FTP | FTPS | AS2

必須：いいえ

S3StorageOptions

Amazon S3 ディレクトリのパフォーマンスを最適化するかどうかを指定します。これはデフォルトでは無効になっています。

デフォルトでは、ホームディレクトリマッピングの は TYPEですDIRECTORY。このオプションを有効にすると、マッピングにファイルターゲットを設定するHomeDirectoryMapEntryTypeFILE場合は、 を明示的に に設定する必要があります。

タイプ：S3StorageOptions オブジェクト

必須: いいえ

SecurityPolicyName

サーバーのセキュリティポリシーの名前を指定します。

型: 文字列

長さの制限: 最小長は 0 です。最大長は 100 です。

Pattern: Transfer[A-Za-z0-9]*SecurityPolicy-[A-Za-z0-9-]+

必須: いいえ

ServerId

Transfer Family ユーザーが割り当てられているサーバーインスタンスのシステム割り当て一意識別子。

型: 文字列

長さの制限: 固定長は 19 です。

Pattern: s-([0-9a-f]{17})

必須：はい

StructuredLogDestinations

サーバーログの送信先となるロググループを指定します。

ロググループを指定するには、既存のロググループの ARN を指定する必要があります。この場合、ロググループの形式は次のようになります。

arn:aws:logs:region-name:amazon-account-id:log-group:log-group-name:*

例えば、次のようになります: arn:aws:logs:us-east-1:111122223333:log-group:mytestgroup:*

以前にサーバーのロググループを指定したことがある場合は、update-server 呼び出し時にこのパラメータに空の値を指定することで、そのロググループをクリアし、構造化ロギングを事実上無効にすることができます。例:

update-server --server-id s-1234567890abcdef0 --structured-log-destinations

タイプ：文字列の配列

配列メンバー: 最小数は 0 項目です。最大数は 1 項目です。

長さの制限: 最小長は 20 です。最大長は 1600 です。

Pattern: arn:\S+

必須: いいえ

WorkflowDetails

割り当てるワークフローのワークフロー ID とワークフローの実行に使用する実行ロールを指定します。

ファイルのアップロード完了時に実行するワークフローに加えて、部分的なアップロードで実行するワークフローのワークフロー ID (および実行ロール) も WorkflowDetails に含めることができます。部分的なアップロードは、ファイルのアップロード中にサーバーセッションが切断されたときに発生します。

関連するワークフローをサーバーから削除するには、以下の例に示すように、空の OnUpload オブジェクトを提供します。

aws transfer update-server --server-id s-01234567890abcdef --workflow-details '{"OnUpload":[]}'

タイプ：WorkflowDetails オブジェクト

必須: いいえ

レスポンスの構文

{
   "ServerId": "string"
}

レスポンス要素

アクションが成功すると、サービスは HTTP 200 レスポンスを返します。

サービスから以下のデータが JSON 形式で返されます。

ServerId

Transfer Family ユーザーが割り当てられているサーバーの、システムから割り当てられた一意の識別子。

型: 文字列

長さの制限: 固定長は 19 です。

パターン：s-([0-9a-f]{17})

エラー

すべてのアクションに共通のエラーについては、「共通エラー」を参照してください。

AccessDeniedException

このアクションを実行する十分なアクセス権限がありません。

HTTP ステータスコード：400

ConflictException

この例外は、エンドポイントタイプが VPC であるファイル転送プロトコル対応サーバーの場合に UpdateServer が呼び出され、サーバーの VpcEndpointID が利用可能な状態でない場合にスローされます。

HTTP ステータスコード：400

InternalServiceError

この例外は、 AWS Transfer Family サービスでエラーが発生した場合にスローされます。

HTTP ステータスコード：500

InvalidRequestException

この例外は、クライアントが不正な形式のリクエストを送信した場合にスローされます。

HTTP ステータスコード：400

ResourceExistsException

要求されたリソースは存在しないか、コマンドに指定されたリージョン以外のリージョンに存在します。

HTTP ステータスコード：400

ResourceNotFoundException

この例外は、 AWS Transfer Family サービスによってリソースが見つからない場合にスローされます。

HTTP ステータスコード：400

ServiceUnavailableException

AWS Transfer Family サービスが利用できないため、リクエストは失敗しました。

HTTP ステータスコード：500

ThrottlingException

リクエストのスロットリングにより、リクエストが拒否されました。

HTTP ステータスコード：400

例

例

次の例では、サーバーのロールを更新します。

リクエスト例


{
   "EndpointDetails": { 
   "VpcEndpointId": "vpce-01234f056f3g13",
   "LoggingRole": "CloudWatchS3Events",
   "ServerId": "s-01234567890abcdef"
   }
}

例

以下の例では、サーバーから関連するワークフローを削除します。

リクエスト例

aws transfer update-server --server-id s-01234567890abcdef --workflow-details '{"OnUpload":[]}'

例

これは、この API コールに対するレスポンスのサンプルです。

レスポンス例

{
   "ServerId": "s-01234567890abcdef"
}

その他の参照資料

言語固有の AWS SDKs のいずれかでこの API を使用する方法の詳細については、以下を参照してください。