As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# AWS Transfer Family Referência da API
O guia completo de referência de API para Transfer Family está disponível em [AWS Transfer Family API Reference](https://docs.aws.amazon.com/transfer/latest/APIReference/api-welcome.html).
AWS Transfer Family é um serviço de transferência segura que você pode usar para transferir arquivos para dentro e para fora do armazenamento do Amazon Simple Storage Service (Amazon S3) usando os seguintes protocolos:
+ Protocolo de Transferência de Arquivos (SFTP) do Secure Shell (SSH)
+ Protocolo de Transferência de Arquivos Seguro (FTPS)
+ Protocolo de Transferência de Arquivos (FTP)
+ Declaração de Aplicabilidade 2 (AS2)
Servidores, usuários e funções são identificados pelo nome de recurso da Amazon (ARN). Você pode atribuir tags, que são pares de chave-valor, a entidades com um ARN. As tags são metadados que podem ser usados para agrupar ou procurar essas entidades. As tags são úteis, por exemplo, para fins de contabilidade.
As seguintes convenções são observadas nos formatos de AWS Transfer Family ID:
+ Os valores `ServerId` assumem a forma `s-01234567890abcdef`.
+ Os valores `SshPublicKeyId` assumem a forma `key-01234567890abcdef`.
Os formatos do nome de recurso da Amazon (ARN) assumem a seguinte forma:
+ Para servidores, os ARNs assumem a forma `arn:aws:transfer:{{region}}:{{account-id}}:server/{{server-id}}`.
Veja o seguinte exemplo de um servidor ARN: `arn:aws:transfer:us-east-1:123456789012:server/s-01234567890abcdef`.
+ Para usuários, os ARNs assumem o formato `arn:aws:transfer:{{region}}:{{account-id}}:user/{{server-id}}/{{username}}`.
Um exemplo é `arn:aws:transfer:us-east-1:123456789012:user/s-01234567890abcdef/user1`.
As entradas DNS (endpoints) em uso são assim:
+ Os endpoints de API assumem o formato `transfer.{{region}}.amazonaws.com`.
+ Os endpoints do servidor assumem o formato `{{server-id}}.server.transfer.{{region}}.amazonaws.com`.
Essa referência de interface de API AWS Transfer Family contém documentação para uma interface de programação que você pode usar para gerenciar AWS Transfer Family. A estrutura da referência é a seguinte:
+ Para uma lista alfabética de ações de API, consulte [Actions](https://docs.aws.amazon.com/transfer/latest/APIReference/API_Operations.html).
+ Para a lista alfabética de tipos de dados, consulte [Types](https://docs.aws.amazon.com/transfer/latest/APIReference/API_Types.html).
+ Para obter uma lista de parâmetros de consulta comuns, consulte [Parâmetros comuns](https://docs.aws.amazon.com/transfer/latest/APIReference/CommonParameters.html).
+ Para obter descrições dos códigos de erro, consulte [Erros comuns](https://docs.aws.amazon.com/transfer/latest/APIReference/CommonErrors.html).
**dica**
Em vez de realmente executar um comando, você pode usar o parâmetro `--generate-cli-skeleton` com qualquer chamada de API para gerar e exibir um modelo de parâmetro. Em seguida, você pode usar o modelo gerado para personalizar e usar como entrada em um comando posterior. Para obter detalhes, consulte [Gerar e usar um arquivo esqueleto de parâmetro](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-skeleton.html#cli-usage-skeleton-generate).
## Como fazer solicitações de API
Além de usar o console, você pode usar a AWS Transfer Family API para configurar e gerenciar programaticamente seus servidores. Esta seção descreve as AWS Transfer Family operações, a assinatura de solicitações para autenticação e o tratamento de erros. Para obter mais informações sobre as regiões e os endpoints disponíveis para o Transfer Family, consulte [AWS Transfer Family endpoints e quotas](https://docs.aws.amazon.com/general/latest/gr/transfer-service.html) no *Referência geral da AWS*
**nota**
Você também pode usar os AWS SDKs ao desenvolver aplicativos com o Transfer Family;. Os SDKs AWS para Java, .NET e PHP encapsulam a API subjacente do Transfer Family para simplificar as tarefas de programação. Para obter informações sobre como fazer download de bibliotecas de SDKs, consulte [Bibliotecas de códigos de exemplo](https://aws.amazon.com/code).
### Cabeçalhos de solicitação obrigatórios do Transfer Family
Esta seção descreve os cabeçalhos requeridos que você precisa enviar em cada solicitação POST ao AWS Transfer Family. Os cabeçalhos HTTP são incluídos para identificar as principais informações sobre a solicitação, como a operação que você deseja invocar, a data da solicitação e informações que indicam sua autorização como remetente da solicitação. Os cabeçalhos diferenciam minúsculas e maiúsculas e a ordem dos cabeçalhos não é importante.
O exemplo a seguir mostra os cabeçalhos que são usados na [ListServers](https://docs.aws.amazon.com/transfer/latest/userguide/API_ListServers.html)operação.
```
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}
```
A seguir encontram-se os cabeçalhos que devem ser incluídos em suas solicitações POST ao Transfer Family. Os cabeçalhos mostrados abaixo que começam com “x-amz” são específicos para. AWS Todos os outros cabeçalhos listados são cabeçalhos comuns usados em transações HTTP.
### Entradas e assinaturas de solicitações do Transfer Family
Todas as entradas da solicitação devem ser enviadas como parte da carga JSON no corpo da solicitação. Para ações em que todos os campos de solicitação são opcionais, por exemplo, `ListServers`, você ainda precisa fornecer um objeto JSON vazio no corpo da solicitação, como `{}`. A estrutura da carga útil do Transfer Family request/response está documentada na referência existente da API, por exemplo [DescribeServer](https://docs.aws.amazon.com/transfer/latest/userguide/API_DescribeServer.html).
O Transfer Family oferece suporte à autenticação usando o AWS Signature Version 4. Para obter detalhes, veja [Assinatura de solicitações da API da AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html).
### Respostas de erro
Quando existe um erro, as informações no cabeçalho da resposta contêm:
+ Content-Type: `application/x-amz-json-1.1`
+ Um código de status HTTP `4xx` ou `5xx` apropriado
O corpo de uma resposta de erro contém informações sobre o erro que ocorreu. A resposta de erro de exemplo a seguir mostra a sintaxe de saída dos elementos comuns a todas as respostas de erro.
```
{
"__type": "String",
"Message": "String",
"Resource": "String",
"ResourceType": "String",
"RetryAfterSeconds": "String"
}
```
A tabela a seguir explica os campos de resposta de erro JSON mostrados na sintaxe anterior.
**\_\_type**
Uma das exceções de uma chamada de API do Transfer Family.
*Tipo:* string
**Mensagem** ou **mensagem**
Uma das mensagens de código de erro de operação em .
Algumas exceções usam `message` e outras usam `Message`. Você pode verificar o código da interface para determinar o caso adequado. Como alternativa, você pode testar cada opção para ver qual funciona.
*Tipo:* string
**Recurso**
O recurso para o qual o erro é invocado. Por exemplo, se você tentar criar um usuário que já existe, o `Resource` será o nome de usuário referente ao usuário existente.
*Tipo:* string
**ResourceType**
O recurso para o qual o erro é invocado. Por exemplo, se você tentar criar um usuário que já existe, o `ResourceType` será `User`.
*Tipo:* string
**RetryAfterSeconds**
O número de segundos a esperar antes de repetir o comando.
*Tipo:* string
#### Exemplos de resposta de erro
O corpo JSON a seguir será retornado se você chamar a API `DescribeServer` e especificar um servidor que não existe.
```
{
"__type": "ResourceNotFoundException",
"Message": "Unknown server",
"Resource": "s-11112222333344444",
"ResourceType": "Server"
}
```
O corpo JSON a seguir será retornado se a execução de uma API causar o controle de utilização.
```
{
"__type":"ThrottlingException",
"RetryAfterSeconds":"1"
}
```
O corpo JSON a seguir será retornado se você usar a API `CreateServer` e não tiver permissões suficientes para criar um servidor do Transfer Family.
```
{
"__type": "AccessDeniedException",
"Message": "You do not have sufficient access to perform this action."
}
```
O corpo JSON a seguir será retornado se você chamar a API `CreateUser` e especificar um servidor que já existe.
```
{
"__type": "ResourceExistsException",
"Message": "User already exists",
"Resource": "Alejandro-Rosalez",
"ResourceType": "User"
}
```
### Bibliotecas disponíveis
AWS fornece bibliotecas, exemplos de código, tutoriais e outros recursos para desenvolvedores de software que preferem criar aplicativos usando APIs específicas da linguagem em vez das ferramentas de linha de comando e da API de consulta. Essas bibliotecas oferecem as funções básicas (não incluídas nas APIs), como autenticação de solicitação, novas tentativas de solicitação e processamento de erros, para que você possa começar a usar com mais facilidade. Veja [as ferramentas para desenvolver AWS](https://aws.amazon.com/tools/?id=docs_gateway)
Para obter bibliotecas e código de exemplo em todos os idiomas, consulte [Código de exemplo e bibliotecas](https://aws.amazon.com/code).
## Provedores de identidade
AWS Transfer Family oferece suporte a vários tipos de provedores de identidade para autenticar e gerenciar usuários. Cada servidor pode usar somente um método de autenticação, que deve ser selecionado quando o servidor é criado.
Serviço gerenciado
Com o método de `SERVICE_MANAGED` autenticação, as credenciais do usuário são armazenadas e gerenciadas nele AWS Transfer Family. Os usuários são autenticados usando chaves públicas SSH associadas ao nome de usuário no servidor.
Cada usuário pode ter uma ou mais chaves públicas SSH armazenadas no serviço. Quando um cliente solicita uma operação de arquivo, ele fornece o nome de usuário e a chave privada SSH, que são autenticados na chave pública armazenada.
Directory Service
O método de `AWS_DIRECTORY_SERVICE` autenticação permite a integração com o AWS Directory Service for Microsoft Active Directory (AWS Directory Service for Microsoft Active Directory).
Essa opção permite gerenciar a autenticação e o acesso do usuário por meio de seus grupos existentes do Active Directory. Os usuários podem se autenticar usando suas credenciais do Active Directory.
Há um limite padrão de 100 grupos do Active Directory por servidor, que pode ser aumentado para um máximo de 150 grupos por meio de um aumento no limite de serviço.
Lambda
O método de `AWS_LAMBDA` autenticação permite que você se conecte a um provedor de identidade personalizado usando AWS Lambda.
Essa opção oferece flexibilidade para integração com seus sistemas de gerenciamento de identidade existentes. A função Lambda é responsável por autenticar usuários e retornar as políticas de acesso apropriadas.
Personalizado (API Gateway)
O método de `API_GATEWAY` autenticação (exibido como **Personalizado** no console) permite que você use um método de autenticação personalizado que fornece autenticação de usuário e controle de acesso.
Este método se baseia no Amazon API Gateway para usar a chamada de API a partir do seu provedor de identidade para validar as solicitações do usuário. Você pode usar esse método personalizado para autenticar usuários em um serviço de diretório, um name/password par de bancos de dados ou algum outro mecanismo.
Para todos os métodos de autenticação, os usuários recebem políticas que definem seu acesso aos buckets do Amazon S3 ou aos sistemas de arquivos do Amazon Elastic File System. O servidor herda a relação de confiança do usuário por meio de uma função do IAM com uma `AssumeRole` ação, permitindo que ele execute operações de arquivo em nome do usuário.
## Convenções de nomenclatura
AWS Transfer Family usa formatos padronizados para identificadores de recursos e Amazon Resource Names (ARNs). Compreender essas convenções é importante ao trabalhar com a AWS Transfer Family API.
### Formatos de identificação
As seguintes convenções são observadas nos formatos de AWS Transfer Family ID:
IDs do servidor
Os valores `ServerId` assumem a forma `s-01234567890abcdef`.
IDs de chave pública SSH
Os valores `SshPublicKeyId` assumem a forma `key-01234567890abcdef`.
IDs do conector
Os valores `ConnectorId` assumem a forma `c-01234567890abcdef`.
ID do fluxo de trabalho
Os valores `WorkflowId` assumem a forma `w-01234567890abcdef`.
IDs de perfil
Os valores `ProfileId` assumem a forma `p-01234567890abcdef`.
WebApp IDs
Os valores `WebAppId` assumem a forma `webapp-01234567890abcdef`.
### Formatos ARN
Os formatos do nome de recurso da Amazon (ARN) assumem a seguinte forma:
ARNs do servidor
Para servidores, os ARNs assumem a forma `arn:aws:transfer:{{region}}:{{account-id}}:server/{{server-id}}`.
Exemplo: `arn:aws:transfer:us-east-1:123456789012:server/s-01234567890abcdef`.
ARNs do usuário
Para usuários, os ARNs assumem o formato `arn:aws:transfer:{{region}}:{{account-id}}:user/{{server-id}}/{{username}}`.
Exemplo: `arn:aws:transfer:us-east-1:123456789012:user/s-01234567890abcdef/user1`.
Conector ARNs
Para conectores, os ARNs assumem o formato. `arn:aws:transfer:{{region}}:{{account-id}}:connector/{{connector-id}}`
Exemplo: `arn:aws:transfer:us-east-1:123456789012:connector/c-01234567890abcdef`.
ARNs de fluxo de trabalho
Para fluxos de trabalho, os ARNs assumem o formato. `arn:aws:transfer:{{region}}:{{account-id}}:workflow/{{workflow-id}}`
Exemplo: `arn:aws:transfer:us-east-1:123456789012:workflow/w-01234567890abcdef`.
WebApp RNs
Para aplicativos da web, os ARNs assumem o formato`arn:aws:transfer:{{region}}:{{account-id}}:webapp/{{webapp-id}}`.
Exemplo: `arn:aws:transfer:us-east-1:123456789012:webapp/webapp-01234567890abcdef`.
Você pode atribuir tags, que são pares de chave-valor, a entidades com um ARN. As tags são metadados que podem ser usados para agrupar ou procurar essas entidades. As tags são úteis, por exemplo, para fins de contabilidade.
## DNS e endpoints
AWS Transfer Family usa convenções de nomenclatura de DNS padronizadas para endpoints de API e endpoints de servidor. Compreender esses endpoints é essencial para configurar clientes e fazer chamadas de API.
### Endpoints da API
Os endpoints de API são usados para fazer chamadas de API para gerenciar AWS Transfer Family recursos. Esses endpoints assumem as seguintes formas:
Endpoints de API padrão
Os endpoints padrão da API assumem o formato`transfer.{{region}}.amazonaws.com`.
Exemplo: `transfer.us-east-1.amazonaws.com`
Dual-Stack Endpoints da API
AWS Transfer Family oferece endpoints de API de pilha dupla que podem ser acessados usando solicitações IPv4 ou IPv6:
+ https://transfer.*{{region-code}}*.api.aws
+ https://transfer-fips.*{{region-code}}*.api.aws
### Endpoints do servidor
Os endpoints do servidor são usados pelos clientes de transferência de arquivos para se conectarem aos AWS Transfer Family servidores. Esses endpoints assumem as seguintes formas:
Endpoints de servidor padrão
Os endpoints de servidor padrão assumem o formato`{{server-id}}.server.transfer.{{region}}.amazonaws.com`.
Exemplo: `s-01234567890abcdef.server.transfer.us-east-1.amazonaws.com`
Nomes de host personalizados
Você também pode configurar nomes de host personalizados para seus AWS Transfer Family servidores. Nomes de host personalizados podem ser usados para fornecer uma experiência mais amigável ou de marca para seus usuários.
Para usar um nome de host personalizado, você deve:
1. Possuir o nome de domínio
1. Forneça um certificado válido
1. Configure os registros DNS para apontar para o seu servidor AWS Transfer Family
Para obter uma lista completa de AWS Transfer Family endpoints por AWS região, consulte os [AWS Transfer Family endpoints e as cotas](https://docs.aws.amazon.com/general/latest/gr/transfer-service.html) no. *Referência geral da AWS*