發送請求
程式碼範例: client-configure-request
在設定用戶端之後,你就可以開始發送 HTTP 請求。主要的方法是使用接受 URL 作為參數的 .request() 函式。在此函式中,你可以設定各種請求參數:
- 指定 HTTP 方法,例如
GET、POST、PUT、DELETE、HEAD、OPTIONS或PATCH。 - 將 URL 設定為字串,或分別設定其各個組件(例如網域、路徑和查詢參數)。
- 使用 Unix domain socket。
- 新增標頭與 Cookie。
- 包含請求主體 – 例如純文字、資料物件或表單參數。
這些參數由 HttpRequestBuilder 類別公開提供。
import io.ktor.client.request.*
import io.ktor.client.statement.*
val response: HttpResponse = client.request("https://ktor.io/") {
// 設定 HttpRequestBuilder 所公開的請求參數
}.request() 函式會以 HttpResponse 物件傳回回應。HttpResponse 公開了取得各種格式的回應主體所需的 API – 例如字串、JSON 物件等 – 以及擷取狀態碼、內容類型與標頭等回應參數。若要了解更多,請參閱接收回應。
.request() 是一個掛起函式(suspending function),這意味著它必須在協同程式或其他掛起函式內部呼叫。若要深入了解掛起函式,請參閱 協同程式基礎。
指定 HTTP 方法
呼叫 .request() 函式時,你可以使用 method 屬性指定所需的 HTTP 方法:
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
val response: HttpResponse = client.request("https://ktor.io/") {
method = HttpMethod.Get
}除了 .request() 之外,HttpClient 還為基本的 HTTP 方法提供了專用函式,例如 .get()、 .post() 和 .put()。 上述範例可以使用 .get() 函式進行簡化:
val response: HttpResponse = client.get("https://ktor.io/docs/welcome.html")在這兩個範例中,請求 URL 都是指定為字串。你也可以使用 HttpRequestBuilder 分別設定 URL 組件。
指定請求 URL
Ktor 用戶端允許你透過多種方式設定請求 URL:
傳入完整 URL 字串
val response: HttpResponse = client.get("https://ktor.io/docs/welcome.html")分別設定 URL 組件
client.get {
url {
protocol = URLProtocol.HTTPS
host = "ktor.io"
path("docs/welcome.html")
}
}在這種情況下,會使用 HttpRequestBuilder 提供的 url 參數。它接受一個 URLBuilder 執行個體,為建構複雜的 URL 提供更高的彈性。
若要為所有請求設定基礎 URL,請使用 DefaultRequest 外掛程式。
路徑片段
在前一個範例中,完整的 URL 路徑是使用 URLBuilder.path 屬性指定的。 或者,你也可以使用 appendPathSegments() 函式傳入各個獨立的路徑片段。
client.get("https://ktor.io") {
url {
appendPathSegments("docs", "welcome.html")
}
}預設情況下,appendPathSegments 會對路徑片段進行編碼。 若要停用編碼,請改用 appendEncodedPathSegments()。
查詢參數
若要新增 查詢字串(query string) 參數,請使用 URLBuilder.parameters 屬性:
client.get("https://ktor.io") {
url {
parameters.append("token", "abc123")
}
}預設情況下,parameters 會對查詢參數進行編碼。 若要停用編碼,請改用 encodedParameters()。
trailingQuery 屬性可用於在即使沒有查詢參數的情況下,仍保留 ? 字元。
URL 片段
井字號 # 用於在 URL 接近結尾處引入可選的片段。 你可以使用 fragment 屬性設定 URL 片段。
client.get("https://ktor.io") {
url {
fragment = "some_anchor"
}
}預設情況下,fragment 會對 URL 片段進行編碼。 若要停用編碼,請改用 encodedFragment()。
指定 Unix domain socket
只有 CIO 引擎支援 Unix domain socket。 若要在 Ktor 伺服器中使用 Unix socket,請相應地設定伺服器。
若要在使用 CIO 用戶端時向監聽 Unix domain socket 的伺服器發送請求,請呼叫 unixSocket() 函式:
val client = HttpClient(CIO)
val response: HttpResponse = client.get("/") {
unixSocket("/tmp/test-unix-socket-ktor.sock")
}你也可以將 Unix domain socket 設定為預設請求的一部分。
設定請求參數
你可以指定各種請求參數,包含 HTTP 方法、標頭和 Cookie。如果你需要為特定用戶端的所有請求設定預設參數,請使用 DefaultRequest 外掛程式。
標頭
你可以透過多種方式向請求新增標頭:
新增多個標頭
headers 函式可讓你一次新增多個標頭:
client.get("https://ktor.io") {
headers {
append(HttpHeaders.Accept, "text/html")
append(HttpHeaders.Authorization, "abc123")
append(HttpHeaders.UserAgent, "ktor client")
}
}你也可以搭配 Map 或 vararg Pair 使用 appendAll() 函式,以方便地新增多個標頭:
client.get("https://ktor.io") {
headers {
// 使用 vararg Pair
appendAll(
HttpHeaders.Accept to "text/html",
HttpHeaders.Authorization to "abc123"
)
// 使用 Map
appendAll(mapOf("foo" to "bar", "baz" to "qux"))
appendAll(mapOf("test" to listOf("1", "2", "3")))
// 使用具有多個值的自訂標頭
appendAll("X-Custom-Header" to listOf("val1", "val2"))
}
}新增單一標頭
header 函式允許你附加單一標頭。
使用 basicAuth 或 bearerAuth 進行授權
basicAuth 與 bearerAuth 函式會加入帶有相應 HTTP scheme 的 Authorization 標頭。
關於進階身分驗證設定,請參閱 Ktor Client 中的身分驗證與授權。
Cookie
若要發送 Cookie,請使用 cookie() 函式:
client.get("https://ktor.io") {
cookie(name = "user_name", value = "jetbrains", expires = GMTDate(
seconds = 0,
minutes = 0,
hours = 10,
dayOfMonth = 1,
month = Month.APRIL,
year = 2023
))
}Ktor 還提供了 HttpCookies 外掛程式,可讓你在多次呼叫之間保持 Cookie。如果已安裝此前置外掛程式,使用 cookie() 函式新增的 Cookie 將會被忽略。
設定請求主體
若要設定請求主體,請呼叫 HttpRequestBuilder 提供的 setBody() 函式。 此函式接受不同類型的有效負載,包含純文字、任意類別執行個體、表單資料以及位元組陣列。
文字
將純文字作為主體發送可以透過以下方式實作:
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
val response: HttpResponse = client.post("http://localhost:8080/post") {
setBody("Body content")
}物件
啟用 ContentNegotiation 外掛程式後,你可以在請求主體中將類別執行個體作為 JSON 發送。為此,請將類別執行個體傳入 setBody() 函式,並使用 contentType() 函式將內容類型設定為 application/json:
val response: HttpResponse = client.post("http://localhost:8080/customer") {
contentType(ContentType.Application.Json)
setBody(Customer(3, "Jet", "Brains"))
}若要了解更多資訊,請參閱 Ktor Client 中的內容協商與序列化。
表單參數
Ktor 用戶端提供了 submitForm() 函式,用於發送 application/x-www-form-urlencoded 類型的表單參數。以下範例示範了其用法:
val client = HttpClient(CIO)
val response: HttpResponse = client.submitForm(
url = "http://localhost:8080/signup",
formParameters = parameters {
append("username", "JetBrains")
append("email", "example@jetbrains.com")
append("password", "foobar")
append("confirmation", "foobar")
}
)url指定發送請求的 URL。formParameters是一組使用parameters建構的表單參數。
如需完整範例,請參閱 client-submit-form。
若要發送編碼在 URL 中的表單參數,請將 encodeInQuery 設定為 true。
上傳檔案
如果你需要隨表單一起發送檔案,可以使用以下方法:
- 使用
.submitFormWithBinaryData()函式。在這種情況下,會自動產生邊界(boundary)。 - 呼叫
post函式,並將MultiPartFormDataContent執行個體傳遞給setBody函式。MultiPartFormDataContent建構函式也允許你傳入自訂的邊界值。
對於這兩種方法,你都需要使用 formData {} 函式來建構表單資料。
使用 .submitFormWithBinaryData()
.submitFormWithBinaryData() 函式會自動產生邊界,適用於檔案內容夠小、可以安全使用 .readBytes() 讀入記憶體的簡易使用案例。
val client = HttpClient(CIO)
val response: HttpResponse = client.submitFormWithBinaryData(
url = "http://localhost:8080/upload",
formData = formData {
append("description", "Ktor logo")
append("image", File("ktor_logo.png").readBytes(), Headers.build {
append(HttpHeaders.ContentType, "image/png")
append(HttpHeaders.ContentDisposition, "filename=\"ktor_logo.png\"")
})
}
)如需完整範例,請參閱 client-upload。
使用 MultiPartFormDataContent
若要有效率地串流傳輸大型或動態內容,你可以將 MultiPartFormDataContent 與 InputProvider 搭配使用。 InputProvider 允許你以緩衝串流形式提供檔案資料,而不是將其全部載入記憶體中,非常適合用於大檔案。使用 MultiPartFormDataContent 時,你還可以使用 onUpload 回呼來監控上傳進度。
val client = HttpClient(CIO)
val file = File("ktor_logo.png")
val response: HttpResponse = client.post("http://localhost:8080/upload") {
setBody(
MultiPartFormDataContent(
formData {
append("description", "Ktor logo")
append(
"image",
InputProvider { file.inputStream().asInput().buffered() },
Headers.build {
append(HttpHeaders.ContentType, "image/png")
append(HttpHeaders.ContentDisposition, "filename=\"ktor_logo.png\"")
}
)
},
boundary = "WebAppBoundary"
)
)
onUpload { bytesSentTotal, contentLength ->
println("Sent $bytesSentTotal bytes from $contentLength")
}
}在多平台專案中,你可以將 SystemFileSystem.source() 與 InputProvider 搭配使用:
InputProvider { SystemFileSystem.source(Path("ktor_logo.png")).buffered() }你也可以手動建構具有自訂邊界與內容類型的 MultiPartFormDataContent:
fun customMultiPartMixedDataContent(parts: List<PartData>): MultiPartFormDataContent {
val boundary = "WebAppBoundary"
val contentType = ContentType.MultiPart.Mixed.withParameter("boundary", boundary)
return MultiPartFormDataContent(parts, boundary, contentType)
}如需完整範例,請參閱 client-upload-progress。
二進制資料
若要發送內容類型為 application/octet-stream 的二進制資料,請將 ByteReadChannel 執行個體傳入 setBody() 函式。 例如,你可以使用 File.readChannel() 函式為檔案開啟讀取通道:
val response = client.post("http://0.0.0.0:8080/upload") {
setBody(File("ktor_logo.png").readChannel())
}如需完整範例,請參閱 client-upload-binary-data。
平行請求
預設情況下,當你循序發送多個請求時,用戶端會掛起每個呼叫,直到前一個呼叫完成。若要並行執行多個請求,請使用 launch() 或 async() 函式。以下範例示範如何使用 async() 平行執行兩個請求:
coroutineScope {
// 平行請求
val firstRequest: Deferred<String> = async { client.get("http://localhost:8080/path1").bodyAsText() }
val secondRequest: Deferred<String> = async { client.get("http://localhost:8080/path2").bodyAsText() }
val firstRequestContent = firstRequest.await()
val secondRequestContent = secondRequest.await()
}如需完整範例,請參閱 client-parallel-requests。
取消請求
若要取消請求,請取消執行該請求的協同程式。 launch() 函式會傳回一個可用於取消正在執行的協同程式的 Job:
import kotlinx.coroutines.*
val client = HttpClient(CIO)
val job = launch {
val requestContent: String = client.get("http://localhost:8080")
}
job.cancel()如需更多詳細資訊,請參閱取消與超時。
