Skip to content

クライアントの依存関係の追加 ​

プロジェクトで Ktor HTTP クライアントを使用するには、リポジトリを設定し、以下の依存関係を追加する必要があります:

  • ktor-client-core

    ktor-client-core には Ktor クライアントのコア機能が含まれています。

  • エンジンの依存関係

    エンジンはネットワークリクエストを処理するために使用されます。特定のプラットフォームでは、ネットワークリクエストを処理するために特定のエンジンが必要になる場合があることに注意してください。

  • (任意) ロギングの依存関係

    構造化された柔軟なロギング機能を実現するためのロギングフレームワークを提供します。

  • (任意) プラグインの依存関係

    プラグインは、特定の機能でクライアントを拡張するために使用されます。

リポジトリの設定

Ktor の依存関係を追加する前に、このプロジェクト用のリポジトリを設定する必要があります:

  • プロダクション

    Ktor のプロダクションリリースは Maven Central リポジトリで提供されています。ビルドスクリプトでこのリポジトリを次のように宣言できます:

    kotlin
    repositories {
        mavenCentral()
    }
    groovy
    repositories {
        mavenCentral()
    }

    プロジェクトは Super POM から Central リポジトリを継承するため、pom.xml ファイルに Maven Central リポジトリを追加する必要はありません。

  • Early Access Program (EAP)

    Ktor の EAP バージョンにアクセスするには、Space リポジトリを参照する必要があります:

    kotlin
    repositories {
        maven {
            url = uri("https://redirector.kotlinlang.org/maven/ktor-eap")
        }
    }
    groovy
    repositories {
        maven {
            url "https://redirector.kotlinlang.org/maven/ktor-eap"
        }
    }
    xml
    <repositories>
        <repository>
            <id>ktor-eap</id>
            <url>https://redirector.kotlinlang.org/maven/ktor-eap</url>
        </repository>
    </repositories>

    Ktor の EAP では Kotlin dev リポジトリが必要になる場合があることに注意してください:

    kotlin
    repositories {
        maven {
            url = uri("https://redirector.kotlinlang.org/maven/dev")
        }
    }
    groovy
    repositories {
        maven {
            url "https://redirector.kotlinlang.org/maven/dev"
        }
    }
    xml
    <repositories>
        <repository>
            <id>ktor-eap</id>
            <url>https://redirector.kotlinlang.org/maven/dev</url>
        </repository>
    </repositories>

依存関係の追加 ​

Ktor はさまざまなプラットフォーム向けに、-jvm や -js などのサフィックスが付いたプラットフォーム固有のアーティファクト(例: ktor-client-core-jvm)を提供しています。Gradle は特定のプラットフォームに適したアーティファクトを自動的に解決しますが、Maven はこの機能をサポートしていないことに注意してください。これは、Maven の場合はプラットフォーム固有のサフィックスを手動で追加する必要があることを意味します。

クライアントの依存関係 ​

メインのクライアント機能は ktor-client-core アーティファクトで提供されています。ビルドシステムに応じて、次のように追加できます:

kotlin
implementation(ktorLibs.client.core)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログを使用しています。
groovy
implementation ktorLibs.client.core
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログを使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-core-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

マルチプラットフォーム ​

マルチプラットフォームプロジェクトの場合は、settings.gradle.kts ファイルに Ktor バージョンカタログをインポートします:

kotlin
dependencyResolutionManagement {
    versionCatalogs {
        create("ktorLibs").from("io.ktor:ktor-version-catalog:3.6.1")
    }
}

次に、ktor-client-core を依存関係として commonMain ソースセットに追加します:

kotlin
kotlin {
    sourceSets {
        commonMain {
            dependencies {
              implementation(ktorLibs.client.core)
            }
        }
    }
}

エンジンの依存関係 ​

エンジンはネットワークリクエストの処理を担当します。Ktor はプラットフォームごとに異なるクライアントエンジンを提供しています。

例えば、CIO エンジンは次のように追加できます:

kotlin
implementation(ktorLibs.client.cio)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログを使用しています。
groovy
implementation ktorLibs.client.cio
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログを使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-cio-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

マルチプラットフォーム ​

デフォルトエンジンの使用 ​

マルチプラットフォームプロジェクトでは、ktor-client-engine-defaults アーティファクトを使用して、各ターゲットプラットフォームに適したクライアントエンジンを提供できます。

このアーティファクトの依存関係を commonMain ソースセットに追加します:

kotlin
kotlin {
    sourceSets {
        commonMain {
            dependencies {
                api(ktorLibs.client.engineDefaults)
            }
        }
    }
}
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログを使用しています。
特定のエンジンの使用 ​

特定のエンジンが必要な場合は、代わりに該当するプラットフォームのソースセットにその依存関係を追加します。例えば、Android で OkHttp を使用するには、androidMain ソースセットに ktorLibs.client.okhttp を追加します:

kotlin
sourceSets {
    androidMain.dependencies {
        implementation(ktorLibs.client.okhttp)
    }
}
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログを使用しています。

各エンジンに必要な依存関係については、エンジンの依存関係の追加を参照してください。

ロギングの依存関係 ​

JVM では、Ktor はロギングの抽象化レイヤーとして Simple Logging Facade for Java (SLF4J) を使用します。SLF4J はロギング API を基盤となるロギング実装から切り離すため、アプリケーションの要件に最も適したロギングフレームワークを統合できます。一般的な選択肢には Logback や Log4j があります。フレームワークが提供されていない場合、SLF4J はデフォルトで無操作 (NOP) 実装になり、実質的にロギングが無効になります。

ロギングを有効にするには、Logback などの必要な SLF4J 実装を含むアーティファクトを追加します:

kotlin
implementation("ch.qos.logback:logback-classic:$logback_version")
groovy
implementation "ch.qos.logback:logback-classic:$logback_version"
xml
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>${logback_version}</version>
</dependency>

Ktor でのロギングの詳細については、Ktor Client のロギングを参照してください。

プラグインの依存関係 ​

Ktor では、認証やシリアライズなど、デフォルトでは利用できない追加のクライアント機能(プラグイン)を使用できます。一部のプラグインは個別のアーティファクトで提供されています。必要な依存関係については、該当するプラグインのトピックで確認できます。

マルチプラットフォームプロジェクトの場合、プラグインの依存関係は commonMain ソースセットに追加する必要があります。一部のプラグインには特定のプラットフォームに対する制限事項がある場合があることに注意してください。

Ktor のバージョンの一貫性を確保する ​

Ktor BOM の依存関係を使用する

Ktor BOM を使用すると、依存関係ごとにバージョンを個別に指定することなく、すべての Ktor モジュールで同一の一貫したバージョンを使用できるようになります。

Ktor BOM の依存関係を追加するには、ビルドスクリプトで次のように宣言します:

kotlin
implementation(platform("io.ktor:ktor-bom:$ktor_version"))
groovy
implementation platform "io.ktor:ktor-bom:$ktor_version"
xml
  <dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.ktor</groupId>
            <artifactId>ktor-bom</artifactId>
            <version>3.6.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

公開されているバージョンカタログを使用する

公開されているバージョンカタログを使用して、Ktor の依存関係宣言を一元化することもできます。このアプローチには以下の利点があります:

  • 独自のカタログで Ktor のバージョンを手動で宣言する必要がなくなります。
  • すべての Ktor モジュールが単一の名前空間の下に公開されます。

カタログを宣言するには、settings.gradle.kts で任意の名前を付けてバージョンカタログを作成します:

kotlin
dependencyResolutionManagement {
    versionCatalogs {
        create("ktorLibs") {
            from("io.ktor:ktor-version-catalog:3.6.1")
        }
    }
}

その後、カタログ名を参照してモジュールの build.gradle.kts に依存関係を追加できます:

kotlin
dependencies {
    implementation(ktorLibs.client.core)
    // ...
}