Membuat permintaan API - AWS Transfer Family
Transfer Family membutuhkan header permintaanTransfer Family meminta masukan dan penandatangananTanggapan kesalahanPustaka yang tersedia

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Membuat permintaan API

Selain menggunakan konsol, Anda dapat menggunakan AWS Transfer Family API untuk mengonfigurasi dan mengelola server secara terprogram. Bagian ini menjelaskan AWS Transfer Family operasi, penandatanganan permintaan untuk otentikasi, dan penanganan kesalahan. Untuk informasi tentang wilayah dan titik akhir yang tersedia untuk Transfer Family, lihat AWS Transfer Familytitik akhir dan kuota di Referensi Umum AWS

catatan

Anda juga dapat menggunakan AWS SDK saat mengembangkan aplikasi dengan Transfer Family;. AWSSDK untuk Java, .NET, dan PHP membungkus Transfer Family API yang mendasarinya, menyederhanakan tugas pemrograman Anda. Untuk informasi tentang mengunduh perpustakaan SDK, lihat Perpustakaan kode sampel.

Transfer Family membutuhkan header permintaan

Bagian ini menjelaskan header yang diperlukan yang harus Anda kirim dengan setiap permintaan POST. AWS Transfer Family Anda menyertakan header HTTP untuk mengidentifikasi informasi kunci tentang permintaan termasuk operasi yang ingin Anda panggil, tanggal permintaan, dan informasi yang menunjukkan otorisasi Anda sebagai pengirim permintaan. Header tidak peka huruf besar/kecil dan urutan header tidak penting.

Contoh berikut menunjukkan header yang digunakan dalam ListServersoperasi.

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}

Berikut ini adalah header yang harus disertakan dengan permintaan POST Anda ke Transfer Family. Header yang ditunjukkan di bawah ini yang dimulai dengan “x-amz” khusus untuk. AWS Semua header lain yang terdaftar adalah header umum yang digunakan dalam transaksi HTTP.

Header Deskripsi
Authorization Header otorisasi diperlukan. Formatnya adalah tanda tangan permintaan Sigv4 standar, yang didokumentasikan pada permintaan AWSAPI Penandatanganan.
Content-Type

Gunakan application/x-amz-json-1.1 sebagai jenis konten untuk semua permintaan ke Transfer Family.

Content-Type: application/x-amz-json-1.1
Host

Gunakan header host untuk menentukan titik akhir Transfer Family tempat Anda mengirim permintaan. Misalnya, transfer.us-east-1.amazonaws.com adalah titik akhir untuk wilayah AS Timur (Ohio). Untuk informasi selengkapnya tentang titik akhir yang tersedia untuk Transfer Family, lihat AWS Transfer Familytitik akhir dan kuota di. Referensi Umum AWS

Host: transfer.region.amazonaws.com
x-amz-date

Anda harus memberikan cap waktu baik di Date header HTTP atau AWS x-amz-date header. (Beberapa pustaka klien HTTP tidak mengizinkan Anda mengatur Date header.) Saat x-amz-date header hadir, Transfer Family mengabaikan Date header apa pun selama otentikasi permintaan. Formatnya harus ISO8601, x-amz-date dalam format YYYYMMDD'T'HHMMSS'Z'.

x-amz-date: YYYYMMDD'T'HHMMSS'Z'
x-amz-target

Header ini menentukan versi API dan operasi yang Anda minta. Nilai header target dibentuk dengan menggabungkan versi API dengan nama API dan dalam format berikut.

x-amz-target: TransferService.operationName

Nilai operationName (ListServersmisalnya) dapat ditemukan dari daftar API,. ListServers
x-amz-security-token Header ini diperlukan ketika kredensi yang digunakan untuk menandatangani permintaan bersifat sementara atau kredensi sesi (untuk detailnya, lihat Menggunakan kredensial sementara dengan AWS sumber daya di Panduan Pengguna IAM. Lihat Menambahkan tanda tangan ke permintaan HTTP di Referensi Umum Amazon Web Services untuk informasi selengkapnya.

Transfer Family meminta masukan dan penandatanganan

Semua input permintaan harus dikirim sebagai bagian dari muatan JSON di badan permintaan. Untuk Tindakan di mana semua bidang permintaan bersifat opsionalListServers, misalnya, Anda masih perlu menyediakan objek JSON kosong di badan permintaan, seperti{}. Struktur permintaan/respons payload Transfer Family didokumentasikan dalam referensi API yang ada, misalnya. DescribeServer

Transfer Family mendukung otentikasi menggunakan AWS Signature Versi 4. Untuk detailnya, lihat Menandatangani permintaan AWS API.

Tanggapan kesalahan

Ketika ada kesalahan, informasi header respons berisi:

  • Tipe Konten: application/x-amz-json-1.1

  • Kode status yang sesuai 4xx atau 5xx HTTP

Tubuh respons kesalahan berisi informasi tentang kesalahan yang terjadi. Contoh respon kesalahan berikut menunjukkan sintaks output elemen respon umum untuk semua respon kesalahan.

{
    "__type": "String",
    "Message": "String", <!-- Message is lowercase in some instances -->
    "Resource": String,
    "ResourceType": String
    "RetryAfterSeconds": String
}

Tabel berikut menjelaskan bidang respons kesalahan JSON yang ditunjukkan dalam sintaks sebelumnya.

__jenis

Salah satu pengecualian dari panggilan Transfer Family API.

Jenis: String

Pesan atau pesan

Salah satu pesan kode kesalahan operasi.

catatan

Beberapa pengecualian digunakanmessage, dan yang lainnya menggunakanMessage. Anda dapat memeriksa kode untuk antarmuka Anda untuk menentukan kasus yang tepat. Atau, Anda dapat menguji setiap opsi untuk melihat mana yang berfungsi.

Jenis: String

Sumber

Sumber daya yang kesalahannya dipanggil. Misalnya, jika Anda mencoba membuat pengguna yang sudah ada, itu Resource adalah nama pengguna untuk pengguna yang ada.

Jenis: String

ResourceType

Jenis sumber daya yang kesalahannya dipanggil. Misalnya, jika Anda mencoba membuat pengguna yang sudah ada, ResourceType isUser.

Jenis: String

RetryAfterSeconds

Jumlah detik untuk menunggu sebelum mencoba kembali perintah.

Jenis: String

Contoh respons kesalahan

Badan JSON berikut dikembalikan jika Anda memanggil DescribeServer API dan menentukan server yang tidak ada.

{
  "__type": "ResourceNotFoundException",
  "Message": "Unknown server",
  "Resource": "s-11112222333344444",
  "ResourceType": "Server"
}

Badan JSON berikut dikembalikan jika menjalankan API menyebabkan pelambatan terjadi.

{
   "__type":"ThrottlingException",
   "RetryAfterSeconds":"1"
}

Badan JSON berikut dikembalikan jika Anda menggunakan CreateServer API dan Anda tidak memiliki izin yang cukup untuk membuat server Transfer Family.

{
  "__type": "AccessDeniedException",
  "Message": "You do not have sufficient access to perform this action."
}

Badan JSON berikut dikembalikan jika Anda menggunakan CreateUser API dan menentukan pengguna yang sudah ada.

{  
  "__type": "ResourceExistsException",  
  "Message": "User already exists",
  "Resource": "Alejandro-Rosalez",
  "ResourceType": "User"
}

Pustaka yang tersedia

AWSmenyediakan pustaka, kode sampel, tutorial, dan sumber daya lainnya untuk pengembang perangkat lunak yang lebih suka membangun aplikasi menggunakan API khusus bahasa alih-alih alat baris perintah dan API Kueri. Pustaka ini menyediakan fungsi dasar (tidak termasuk dalam API), seperti otentikasi permintaan, percobaan ulang permintaan, dan penanganan kesalahan sehingga lebih mudah untuk memulai. Lihat Alat untuk dibangun AWS

Untuk pustaka dan kode sampel dalam semua bahasa, lihat Contoh kode & pustaka.