翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS Transfer Family API リファレンス
Transfer Family の完全な API リファレンスガイドは、 [AWS Transfer Family API リファレンス](https://docs.aws.amazon.com/transfer/latest/APIReference/api-welcome.html)で入手できます。
AWS Transfer Family は、次のプロトコルを介して Amazon Simple Storage Service (Amazon S3) ストレージとの間でファイルを転送するために使用できる安全な転送サービスです。
+ Secure Shell (SSH) File Transfer Protocol (SFTP)
+ File Transfer Protocol Secure (FTPS)
+ File Transfer Protocol (FTP)
+ 適用性ステートメント 2 (AS2)
サーバー、ユーザー、およびロールはすべて、Amazon リソースネーム (ARN) で識別されます。ARN が含まれているエンティティにキーバリューペアであるタグを割り当てることができます。タグは、これらのエンティティのグループ化または検索に使用できるメタデータです。タグが便利な例としては、経理上の処理が挙げられます。
AWS Transfer Family ID 形式では、次の規則が適用されます。
+ `ServerId` 値の形式は `s-01234567890abcdef` です。
+ `SshPublicKeyId` 値の形式は `key-01234567890abcdef` です。
Amazon リソースネーム (ARN) は次のような形式です。
+ ユーザーの場合、ARN の形式は `arn:aws:transfer:{{region}}:{{account-id}}:server/{{server-id}}` です。
サーバー ARN の例: `arn:aws:transfer:us-east-1:123456789012:server/s-01234567890abcdef`
+ ユーザーの場合、ARN の形式は `arn:aws:transfer:{{region}}:{{account-id}}:user/{{server-id}}/{{username}}` です。
例は `arn:aws:transfer:us-east-1:123456789012:user/s-01234567890abcdef/user1` です。
使用する DNS エントリ (エンドポイント) は次のとおりです。
+ API エンドポイントの形式は `transfer.{{region}}.amazonaws.com` です。
+ サーバーエンドポイントの形式は `{{server-id}}.server.transfer.{{region}}.amazonaws.com` です。
この の API インターフェイスリファレンス AWS Transfer Family には、管理に使用できるプログラミングインターフェイスのドキュメントが含まれています AWS Transfer Family。リファレンス構造は次のとおりです。
+ API アクションのアルファベット順リストについては、「[Actions](https://docs.aws.amazon.com/transfer/latest/APIReference/API_Operations.html)」を参照してください。
+ データ型のアルファベット順リストについては、「[Types](https://docs.aws.amazon.com/transfer/latest/APIReference/API_Types.html)」を参照してください。
+ 共通クエリパラメータのリストについては、「[共通パラメータ](https://docs.aws.amazon.com/transfer/latest/APIReference/CommonParameters.html)」を参照してください。
+ エラーコードの説明については、「[共通エラー](https://docs.aws.amazon.com/transfer/latest/APIReference/CommonErrors.html)」を参照してください。
**ヒント**
実際にコマンドを実行する代わりに、任意の API コールで `--generate-cli-skeleton` パラメータを使用してパラメータテンプレートを生成して表示できます。生成されたテンプレートを使用してカスタマイズし、後のコマンドの入力として使用できます。詳細については、「[パラメータスケルトンファイルを生成して使用するには](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-skeleton.html#cli-usage-skeleton-generate)」を参照してください。
## API リクエストを作成する
コンソールの使用に加えて、 AWS Transfer Family API を使用してプログラムでサーバーを設定および管理できます。このセクションでは、 AWS Transfer Family オペレーション、認証のリクエスト署名、エラー処理について説明します。トランスファーファミリーで利用可能なリージョンとエンドポイントについては、「AWS 全般のリファレンス」の「[AWS Transfer Family エンドポイントとクォータ](https://docs.aws.amazon.com/general/latest/gr/transfer-service.html)」を参照してください。
**注記**
Transfer Family でアプリケーションを開発するときに、 AWS SDKs を使用することもできます。Java、.NET、PHP 用の AWS SDK は、基盤となる Transfer Family API をラップし、プログラミング作業を簡素化します。SDK ライブラリのダウンロードについては、「[サンプルコードライブラリ](https://aws.amazon.com/code)」を参照してください。
### Transfer Family に必要なリクエストヘッダー
このセクションでは、 AWS Transfer Familyへのすべての POST リクエストで送信しなければならない必須ヘッダーについて説明します。HTTP ヘッダーでは、呼び出すオペレーション、リクエストの日付、リクエストの送信者として認可されていることを示す情報など、リクエストに関する重要な情報を特定します。ヘッダーは大文字と小文字を区別されず、ヘッダーの順序は重要ではありません。
次の例は、「[ListServers](https://docs.aws.amazon.com/transfer/latest/userguide/API_ListServers.html)」操作で使用されるヘッダーを示しています。
```
POST / HTTP/1.1
Host: transfer.us-east-1.amazonaws.com
x-amz-target: TransferService.ListServers
x-amz-date: 20220507T012034Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20220507/us-east-1/transfer/aws4_request,
SignedHeaders=content-type;host;x-amz-date;x-amz-target,
Signature=13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de
Content-Type: application/x-amz-json-1.1
Content-Length: 17
{"MaxResults":10}
```
以下は、Transfer Family への POST リクエストに含めなければならないヘッダーです。以下に示す「x-amz」で始まるヘッダーは に固有です AWS。それ以外のヘッダーはすべて、HTTP トランザクションで使用される共通のヘッダーです。
### Transfer Family リクエストの入力と署名
すべてのリクエスト入力は、リクエスト本文の JSON ペイロードの一部として送信する必要があります。すべてのリクエスト・フィールドがオプショナルであるアクション（例えば `ListServers`）では、リクエスト・ボディに空の JSON オブジェクト（`{}` など）を提供する必要があります。Transfer Family ペイロードのリクエスト/レスポンスの構造は、例えば、「[DescribeServer](https://docs.aws.amazon.com/transfer/latest/userguide/API_DescribeServer.html)」のような既存の API リファレンスに記載されています。
Transfer Family は、 AWS 署名バージョン 4 を使用した認証をサポートしています。詳細については、「[AWS API リクエストへの署名](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html)」を参照してください。
### エラーレスポンス
エラーが発生した場合、レスポンスヘッダー情報には、以下の項目が含まれています。
+ Content-Type：`application/x-amz-json-1.1`
+ 適切な `4xx` または `5xx` HTTP ステータスコード
エラーレスポンスの本文には、発生したエラーに関する情報が含まれています。次のサンプルエラーは、すべてのエラーレスポンスに共通する、レスポンスエレメントの出力構文を示します。
```
{
"__type": "String",
"Message": "String",
"Resource": "String",
"ResourceType": "String",
"RetryAfterSeconds": "String"
}
```
次の表では、前述の構文で表示される JSON エラーレスポンスフィールドを説明します。
**\_\_type**
Transfer Family API コールの例外の 1 つ。
*タイプ*: 文字列
「**メッセージ**」または「**メッセージ**」
オペレーションエラーコードメッセージの 1 つ 。
`message`を使用する例外もあれば、`Message`を使用する例外もあります。インターフェイスのコードを確認して、適切なケースを判断できます。あるいは、各オプションをテストして、どれが機能するかを確認することもできます。
*タイプ*: 文字列
**[リソース]**
エラーが発生したリソース。たとえば、すでに存在するユーザーを作成しようとすると、`Resource`は既存のユーザーのユーザー名になります。
*タイプ*: 文字列
**ResourceType**
エラーが発生したリソースタイプ。例えば、すでに存在するユーザーを作成しようとすると、`ResourceType`は`User`になります。
*タイプ*: 文字列
**秒後に再試行**
コマンドを再試行する前に待つ秒数。
*タイプ*: 文字列
#### エラーレスポンスの例
`DescribeServer`API を呼び出し、存在しないサーバーを指定すると、次の JSON 本文が返されます。
```
{
"__type": "ResourceNotFoundException",
"Message": "Unknown server",
"Resource": "s-11112222333344444",
"ResourceType": "Server"
}
```
API を実行してスロットリングが発生すると、次の JSON 本文が返されます。
```
{
"__type":"ThrottlingException",
"RetryAfterSeconds":"1"
}
```
`CreateServer`API を使用していて、Transfer Family サーバーを作成するための十分な権限がない場合は、次の JSON 本文が返されます。
```
{
"__type": "AccessDeniedException",
"Message": "You do not have sufficient access to perform this action."
}
```
`CreateUser`API を使用し、すでに存在するユーザーを指定すると、次の JSON 本文が返されます。
```
{
"__type": "ResourceExistsException",
"Message": "User already exists",
"Resource": "Alejandro-Rosalez",
"ResourceType": "User"
}
```
### 利用可能なライブラリ
AWS は、コマンドラインツールやクエリ API の代わりに言語固有の APIs を使用してアプリケーションを構築するソフトウェア開発者向けに、ライブラリ、サンプルコード、チュートリアル、その他のリソースを提供します。これらのライブラリは、リクエスト認証、リクエストの再試行、エラー処理などの基本的な機能（API には含まれていない）を提供するため、簡単に使い始めることができます。[「 で構築するツール AWS](https://aws.amazon.com/tools/?id=docs_gateway)」を参照してください。
すべての言語のライブラリとサンプルコードについては、「[サンプルコードとライブラリ](https://aws.amazon.com/code)」を参照してください。
## ID プロバイダー
AWS Transfer Family は、ユーザーを認証および管理するための複数の ID プロバイダータイプをサポートしています。各サーバーは 1 つの認証方法のみを使用できます。認証方法は、サーバーの作成時に選択する必要があります。
サービスマネージド
`SERVICE_MANAGED` 認証方法では、ユーザー認証情報は 内に保存および管理されます AWS Transfer Family。ユーザーは、サーバー上のユーザー名に関連付けられた SSH パブリックキーを使用して認証されます。
各ユーザーは、1 つ以上の SSH パブリックキーをサービスに保存できます。クライアントがファイルオペレーションをリクエストすると、ユーザー名と SSH プライベートキーが提供され、保存されたパブリックキーに対して認証されます。
Directory Service
`AWS_DIRECTORY_SERVICE` 認証方法では、 AWS Directory Service for Microsoft Active Directory () と統合できますAWS Directory Service for Microsoft Active Directory。
このオプションを使用すると、既存の Active Directory グループを介してユーザー認証とアクセスを管理できます。ユーザーは Active Directory 認証情報を使用して認証できます。
サーバーごとに 100 個の Active Directory グループというデフォルトの制限があり、サービス制限の引き上げにより最大 150 個のグループに増やすことができます。
Lambda
`AWS_LAMBDA` 認証方法では、 を使用してカスタム ID プロバイダーに接続できます AWS Lambda。
このオプションは、既存の ID 管理システムと統合する柔軟性を提供します。Lambda 関数は、ユーザーを認証し、適切なアクセスポリシーを返す責任があります。
カスタム (API Gateway)
`API_GATEWAY` 認証方法 (コンソールでは**カスタム**として表示) では、ユーザー認証とアクセスコントロールの両方を提供するカスタム認証方法を使用できます。
このメソッドは Amazon API Gateway に依存しており、ID プロバイダーからの API コールを使用して、ユーザーリクエストを検証します。このカスタムメソッドを使用して、ディレクトリサービス、データベース名とパスワードのペア、またはその他のメカニズムに対してユーザーを認証できる場合があります。
すべての認証方法で、ユーザーには Amazon S3 バケットまたは Amazon Elastic File System ファイルシステムへのアクセスを定義するポリシーが割り当てられます。サーバーは、 `AssumeRole` アクションを持つ IAM ロールを通じてユーザーから信頼関係を継承し、ユーザーに代わってファイルオペレーションを実行できるようにします。
## 命名規則
AWS Transfer Family は、リソース識別子と Amazon リソースネーム (ARNs) に標準化された形式を使用します。API を使用するときは、 AWS Transfer Family これらの規則を理解することが重要です。
### ID 形式
AWS Transfer Family ID 形式では、次の規則が適用されます。
サーバー IDs
`ServerId` 値の形式は `s-01234567890abcdef` です。
SSH パブリックキー IDs
`SshPublicKeyId` 値の形式は `key-01234567890abcdef` です。
コネクタ IDs
`ConnectorId` 値の形式は `c-01234567890abcdef` です。
ワークフロー IDs
`WorkflowId` 値の形式は `w-01234567890abcdef` です。
プロファイル IDs
`ProfileId` 値の形式は `p-01234567890abcdef` です。
WebApp IDs
`WebAppId` 値の形式は `webapp-01234567890abcdef` です。
### ARN 形式
Amazon リソースネーム (ARN) は次のような形式です。
サーバー ARNs
ユーザーの場合、ARN の形式は `arn:aws:transfer:{{region}}:{{account-id}}:server/{{server-id}}` です。
例えば、`arn:aws:transfer:us-east-1:123456789012:server/s-01234567890abcdef` などです。
ユーザー ARNs
ユーザーの場合、ARN の形式は `arn:aws:transfer:{{region}}:{{account-id}}:user/{{server-id}}/{{username}}` です。
例えば、`arn:aws:transfer:us-east-1:123456789012:user/s-01234567890abcdef/user1` などです。
コネクタ ARNs
コネクタの場合、ARNs の形式になります`arn:aws:transfer:{{region}}:{{account-id}}:connector/{{connector-id}}`。
例えば、`arn:aws:transfer:us-east-1:123456789012:connector/c-01234567890abcdef` などです。
ワークフロー ARNs
ワークフローの場合、ARNs の形式になります`arn:aws:transfer:{{region}}:{{account-id}}:workflow/{{workflow-id}}`。
例えば、`arn:aws:transfer:us-east-1:123456789012:workflow/w-01234567890abcdef` などです。
WebApp ARNs
ウェブアプリケーションARNs は の形式になります`arn:aws:transfer:{{region}}:{{account-id}}:webapp/{{webapp-id}}`。
例えば、`arn:aws:transfer:us-east-1:123456789012:webapp/webapp-01234567890abcdef` などです。
ARN が含まれているエンティティにキーバリューペアであるタグを割り当てることができます。タグは、これらのエンティティのグループ化または検索に使用できるメタデータです。タグが便利な例としては、経理上の処理が挙げられます。
## DNS とエンドポイント
AWS Transfer Family は、API エンドポイントとサーバーエンドポイントの両方に標準化された DNS 命名規則を使用します。これらのエンドポイントを理解することは、クライアントの設定と API コールの実行に不可欠です。
### API エンドポイント
API エンドポイントは、 AWS Transfer Family リソースを管理する API コールを行うために使用されます。これらのエンドポイントの形式は次のとおりです。
標準 API エンドポイント
標準 API エンドポイントの形式は です`transfer.{{region}}.amazonaws.com`。
例: `transfer.us-east-1.amazonaws.com`
デュアルスタック API エンドポイント
AWS Transfer Family には、IPv4 または IPv6 リクエストを使用してアクセスできるデュアルスタック API エンドポイントが用意されています。
+ https://transfer.*{{region-code}}*.api.aws
+ https://transfer-fips.*{{region-code}}*.api.aws
### サーバーエンドポイント
サーバーエンドポイントは、ファイル転送クライアントが AWS Transfer Family サーバーに接続するために使用します。これらのエンドポイントの形式は次のとおりです。
標準サーバーエンドポイント
標準サーバーエンドポイントの形式は です`{{server-id}}.server.transfer.{{region}}.amazonaws.com`。
例: `s-01234567890abcdef.server.transfer.us-east-1.amazonaws.com`
カスタムホスト名
AWS Transfer Family サーバーのカスタムホスト名を設定することもできます。カスタムホスト名を使用すると、ユーザーにわかりやすいエクスペリエンスやブランドエクスペリエンスを提供できます。
カスタムホスト名を使用するには、以下を行う必要があります。
1. ドメイン名を所有する
1. 有効な証明書を提供する
1. AWS Transfer Family サーバーを指すように DNS レコードを設定する
AWS リージョン別の AWS Transfer Family エンドポイントの完全なリストについては、「」の[AWS Transfer Family 「エンドポイントとクォータ](https://docs.aws.amazon.com/general/latest/gr/transfer-service.html)」を参照してください*AWS 全般のリファレンス*。