--- title: Java SDK url: https://platform.claude.com/docs/ja/cli-sdks-libraries/sdks/java description: ビルダーパターンと非同期サポートを備えたAnthropic Java SDKのインストールと設定 --- Anthropic Java SDKは、Javaで書かれたアプリケーションからClaude APIへの便利なアクセスを提供します。リクエストの作成にはビルダーパターンを使用し、同期操作と非同期操作の両方をサポートしています。 コード例を含むAPI機能のドキュメントについては、[APIリファレンス](https://platform.claude.com/docs/ja/api/overview)を参照してください。このページでは、Java固有のSDK機能と設定について説明します。 ## インストール ```kotlin implementation("com.anthropic:anthropic-java:2.73.0") ``` ```xml com.anthropic anthropic-java 2.73.0 ``` ## 要件 このライブラリにはJava 8以降が必要です。 SDKはJava 8以降をサポートしています。このドキュメントのコード例は、素の `void main()` エントリポイントと出力用の `IO.println()` を使用する[JDK 25コンパクトソースファイル](https://openjdk.org/jeps/512)として書かれています。API呼び出し自体は、サポートされているすべてのJDKで同一です。以前のバージョンで例をコンパイルするには、`IO.println(...)` を `System.out.println(...)` に置き換え、本体をクラス内の `public static void main(String[] args)` の中に配置してください。 ## クイックスタート ```java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; // `anthropic.apiKey`、`anthropic.authToken`、`anthropic.baseUrl` システムプロパティを使用して設定します // または、`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL` 環境変数を使用して設定します AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .maxTokens(1024L) .addUserMessage("Hello, Claude") .model(Model.CLAUDE_OPUS_5_5) .build(); Message message = client.messages().create(params); ``` ## クライアント設定 ### APIキーのセットアップ システムプロパティまたは環境変数を使用してクライアントを設定します。 ```java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; // `anthropic.apiKey`、`anthropic.authToken`、`anthropic.baseUrl`のシステムプロパティを使用して設定します // または`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL`の環境変数を使用して設定します AnthropicClient client = AnthropicOkHttpClient.fromEnv(); ``` または手動で設定します。 ```java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; AnthropicClient client = AnthropicOkHttpClient.builder() .apiKey("my-anthropic-api-key") .build(); ``` または両方のアプローチを組み合わせて使用します。 ```java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; AnthropicClient client = AnthropicOkHttpClient.builder() // システムプロパティまたは環境変数を使用して設定します .fromEnv() .apiKey("my-anthropic-api-key") .build(); ``` Workload Identity Federationを含む認証オプションについては、[認証](https://platform.claude.com/docs/ja/manage-claude/authentication)を参照してください。お使いのAPIキーが複数のワークスペースにアクセスできる[個人キーまたはサービスアカウントキー](https://platform.claude.com/docs/ja/manage-claude/authentication#key-types)である場合は、`anthropic-workspace-id`リクエストヘッダーにワークスペースIDを設定してください。[ワークスペースを選択する](https://platform.claude.com/docs/ja/manage-claude/authentication#select-a-workspace)では、このSDKにおけるリクエストごとのオプションを示しています。 ### 設定オプション | セッター | システムプロパティ | 環境変数 | 必須 | デフォルト値 | | ----------- | --------------------- | ---------------------- | ----- | ----------------------------- | | `apiKey` | `anthropic.apiKey` | `ANTHROPIC_API_KEY` | false | - | | `authToken` | `anthropic.authToken` | `ANTHROPIC_AUTH_TOKEN` | false | - | | `baseUrl` | `anthropic.baseUrl` | `ANTHROPIC_BASE_URL` | true | `"https://api.anthropic.com"` | システムプロパティは環境変数よりも優先されます。 同じアプリケーション内で複数のクライアントを作成しないでください。各クライアントは接続プールとスレッドプールを持っており、これらはリクエスト間で共有する方が効率的です。 ### 設定の変更 同じ接続プールとスレッドプールを再利用しながら、変更したクライアント設定を一時的に使用するには、任意のクライアントまたはサービスで `withOptions()` を呼び出します。 ```java import com.anthropic.client.AnthropicClient; AnthropicClient clientWithOptions = client.withOptions(optionsBuilder -> { optionsBuilder.baseUrl("https://example.com"); optionsBuilder.maxRetries(42); }); ``` `withOptions()` メソッドは、元のクライアントやサービスには影響しません。 ## 非同期の使用 デフォルトのクライアントは同期型です。非同期実行に切り替えるには、`async()` メソッドを呼び出します。 ```java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .maxTokens(1024L) .addUserMessage("Hello, Claude") .model(Model.CLAUDE_OPUS_5_5) .build(); CompletableFuture message = client.async().messages().create(params); ``` または最初から非同期クライアントを作成します。 ```java import com.anthropic.client.AnthropicClientAsync; import com.anthropic.client.okhttp.AnthropicOkHttpClientAsync; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; AnthropicClientAsync client = AnthropicOkHttpClientAsync.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .maxTokens(1024L) .addUserMessage("Hello, Claude") .model(Model.CLAUDE_OPUS_5_5) .build(); CompletableFuture message = client.messages().create(params); ``` 非同期クライアントは同期クライアントと同じオプションをサポートしますが、ほとんどのメソッドが `CompletableFuture` を返す点が異なります。 ## ストリーミング SDKは、レスポンスの「チャンク」ストリームを返すメソッドを定義しています。各チャンクは、完全なレスポンスを待つのではなく、到着するとすぐに個別に処理できます。 ### 同期ストリーミング これらの「streaming」（ストリーミング）メソッドは、同期クライアントに対して `StreamResponse` を返します。 ```java import com.anthropic.core.http.StreamResponse; import com.anthropic.models.messages.RawMessageStreamEvent; try (StreamResponse streamResponse = client.messages().createStreaming(params)) { streamResponse.stream().forEach(chunk -> { IO.println(chunk); }); IO.println("No more chunks!"); } ``` ### 非同期ストリーミング 非同期クライアントの場合、メソッドは `AsyncStreamResponse` を返します。 ```java import com.anthropic.core.http.AsyncStreamResponse; import com.anthropic.models.messages.RawMessageStreamEvent; client.async().messages().createStreaming(params).subscribe(chunk -> { IO.println(chunk); }); // ストリームのエラーや完了を処理する必要がある場合 client.async().messages().createStreaming(params).subscribe(new AsyncStreamResponse.Handler<>() { @Override public void onNext(RawMessageStreamEvent chunk) { IO.println(chunk); } @Override public void onComplete(Optional error) { if (error.isPresent()) { IO.println("Something went wrong!"); throw new RuntimeException(error.get()); } else { IO.println("No more chunks!"); } } }); // またはfutureを使用する client.async().messages().createStreaming(params) .subscribe(chunk -> { IO.println(chunk); }) .onCompleteFuture() .whenComplete((unused, error) -> { if (error != null) { IO.println("Something went wrong!"); throw new RuntimeException(error); } else { IO.println("No more chunks!"); } }); ``` 非同期ストリーミングは、現在のスレッドをブロックせずにストリーミングするために、クライアントごとの専用キャッシュスレッドプール `Executor` を使用します。別の `Executor` を使用するには、次のようにします。 ```java Executor executor = Executors.newFixedThreadPool(4); client.async().messages().createStreaming(params).subscribe( chunk -> IO.println(chunk), executor ); ``` または `streamHandlerExecutor` メソッドを使用してクライアントをグローバルに設定します。 ```java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; AnthropicClient client = AnthropicOkHttpClient.builder() .fromEnv() .streamHandlerExecutor(Executors.newFixedThreadPool(4)) .build(); ``` ### メッセージアキュムレータを使用したストリーミング `MessageAccumulator` は、レスポンス内のイベントのストリームを処理しながら記録し、非ストリーミングAPIで返されるものと同様の `Message` オブジェクトを蓄積できます。 同期レスポンスの場合、各イベントを蓄積するためにストリームパイプラインに `Stream.peek()` 呼び出しを追加します。 ```java import com.anthropic.core.http.StreamResponse; import com.anthropic.helpers.MessageAccumulator; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.RawMessageStreamEvent; MessageAccumulator messageAccumulator = MessageAccumulator.create(); try (StreamResponse streamResponse = client.messages().createStreaming(createParams)) { streamResponse.stream() .peek(messageAccumulator::accumulate) .flatMap(event -> event.contentBlockDelta().stream()) .flatMap(deltaEvent -> deltaEvent.delta().text().stream()) .forEach(textDelta -> IO.print(textDelta.text())); } Message message = messageAccumulator.message(); ``` 非同期レスポンスの場合、`subscribe()` 呼び出しに `MessageAccumulator` を追加します。 ```java import com.anthropic.helpers.MessageAccumulator; import com.anthropic.models.messages.Message; MessageAccumulator messageAccumulator = MessageAccumulator.create(); client.async().messages() .createStreaming(createParams) .subscribe(event -> messageAccumulator.accumulate(event).contentBlockDelta().stream() .flatMap(deltaEvent -> deltaEvent.delta().text().stream()) .forEach(textDelta -> IO.print(textDelta.text()))) .onCompleteFuture() .join(); Message message = messageAccumulator.message(); ``` `BetaMessage` オブジェクトの蓄積のために `BetaMessageAccumulator` も利用できます。これは `MessageAccumulator` と同じ方法で使用します。 ## 構造化出力 Javaの例を含む構造化出力の完全なドキュメントについては、[構造化出力](https://platform.claude.com/docs/ja/build-with-claude/structured-outputs)を参照してください。 ## ツール使用 [Claudeでのツール使用](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/overview)（tool use）により、外部ツールや関数をAIモデルのレスポンスに直接統合できます。プレーンテキストを生成する代わりに、モデルは適切な場合にツールや関数を呼び出すための指示（パラメータ付き）を出力できます。ツールのJSONスキーマを定義すると、モデルはそのスキーマを使用して、これらのツールをいつどのように使用するかを判断します。 ツール使用機能は、AIモデルからのJSON出力が入力パラメータで提供したJSONスキーマに準拠することを保証する「strict」モードをサポートしています。 SDKは、任意のJavaクラスの構造からツールとそのパラメータを自動的に導出できます。クラス名（スネークケースに変換）がツール名となり、クラスのフィールドがツールのパラメータを定義します。 ツールクラスはトップレベルクラスまたは `static` ネストクラスとして宣言してください。この要件はJackson Databindライブラリ（`com.fasterxml.jackson.databind`）に由来します。SDKはこのライブラリを使用してツール入力をクラスインスタンスにデシリアライズしますが、非staticの内部クラスはインスタンス化できません。 ### アノテーションによるツールの定義 ```java import com.fasterxml.jackson.annotation.JsonClassDescription; import com.fasterxml.jackson.annotation.JsonPropertyDescription; enum Unit { CELSIUS, FAHRENHEIT; public String toString() { return switch (this) { case CELSIUS -> "C"; case FAHRENHEIT -> "F"; }; } public double fromKelvin(double temperatureK) { return switch (this) { case CELSIUS -> temperatureK - 273.15; case FAHRENHEIT -> (temperatureK - 273.15) * 1.8 + 32.0; }; } } @JsonClassDescription("Get the weather in a given location") static class GetWeather { @JsonPropertyDescription("The city and state, e.g. San Francisco, CA") public String location; @JsonPropertyDescription("The unit of temperature") public Unit unit; public Weather execute() { double temperatureK = switch (location) { case "San Francisco, CA" -> 300.0; case "New York, NY" -> 310.0; case "Dallas, TX" -> 305.0; default -> 295; }; return new Weather(String.format("%.0f%s", unit.fromKelvin(temperatureK), unit)); } } static class Weather { public String temperature; public Weather(String temperature) { this.temperature = temperature; } } ``` ### ツールの呼び出し ツールクラスを定義したら、`MessageCreateParams.Builder.addTool(Class)` を使用してメッセージパラメータに追加し、AIモデルのレスポンスで要求された場合にそれらを呼び出します。`BetaToolUseBlock.input(Class)` を使用すると、JSON形式のツールのパラメータをツール定義クラスのインスタンスにパースできます。 ツールを呼び出した後、`BetaToolResultBlockParam.Builder.contentAsJson(Object)` を使用してツールの結果をAIモデルに返します。 ```java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.messages.*; import com.anthropic.models.messages.Model; AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams.Builder createParamsBuilder = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(2048) .addTool(GetWeather.class) .addUserMessage("What's the temperature in New York?"); client.beta().messages().create(createParamsBuilder.build()).content().stream() .flatMap(contentBlock -> contentBlock.toolUse().stream()) .forEach(toolUseBlock -> createParamsBuilder // ツール使用がリクエストされたことを示すメッセージを追加します。 .addAssistantMessageOfBetaContentBlockParams( List.of(BetaContentBlockParam.ofToolUse(BetaToolUseBlockParam.builder() .name(toolUseBlock.name()) .id(toolUseBlock.id()) .input(toolUseBlock._input()) .build()))) // リクエストされたツール使用の結果を含むメッセージを追加します。 .addUserMessageOfBetaContentBlockParams( List.of(BetaContentBlockParam.ofToolResult(BetaToolResultBlockParam.builder() .toolUseId(toolUseBlock.id()) .contentAsJson(callTool(toolUseBlock)) .build())))); client.beta().messages().create(createParamsBuilder.build()).content().stream() .flatMap(contentBlock -> contentBlock.text().stream()) .forEach(textBlock -> IO.println(textBlock.text())); private static Object callTool(BetaToolUseBlock toolUseBlock) { if (!"get_weather".equals(toolUseBlock.name())) { throw new IllegalArgumentException("Unknown tool: " + toolUseBlock.name()); } GetWeather tool = toolUseBlock.input(GetWeather.class); return tool != null ? tool.execute() : new Weather("unknown"); } ``` ### ツール名の変換 ツール名は、キャメルケースのツールクラス名（例：`GetWeather`）から導出され、スネークケース（例：`get_weather`）に変換されます。単語の境界は、現在の文字が最初の文字ではなく、大文字であり、かつ直前の文字が小文字であるか、直後の文字が小文字である位置から始まります。例えば、`MyJSONParser` は `my_json_parser` になり、`ParseJSON` は `parse_json` になります。この変換は `@JsonTypeName` アノテーションを使用して上書きできます。 ### ローカルでのツールJSONスキーマ検証 ツールクラスから導出されたJSONスキーマがAnthropicの制限に従っていることを確認するために、ローカル検証を実行できます。ローカル検証はデフォルトで有効ですが、無効にすることもできます。 ```java MessageCreateParams.Builder createParamsBuilder = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(2048) .addTool(GetWeather.class, JsonSchemaLocalValidation.NO) .addUserMessage("What's the temperature in New York?"); ``` ### ツールクラスへのアノテーション付与 アノテーションを使用して、ツールに関する追加情報をJSONスキーマに加えることができます。 * `@JsonClassDescription` - ツールクラスに、そのツールをいつどのように使用するかを詳述する説明を追加します。 * `@JsonTypeName` - ツール名を、クラスの単純名をスネークケースに変換したもの以外に設定します。 * `@JsonPropertyDescription` - ツールパラメータに詳細な説明を追加します。 * `@JsonIgnore` - ツールのパラメータ用に生成されるJSONスキーマから `public` フィールドまたはgetterメソッドを除外します。 * `@JsonProperty` - ツールのパラメータ用に生成されるJSONスキーマに非 `public` フィールドまたはgetterメソッドを含めます。 ## メッセージバッチ SDKは `client.messages().batches()` 名前空間の下で[バッチ処理](https://platform.claude.com/docs/ja/build-with-claude/batch-processing)のサポートを提供します。バッチの一覧表示とページネーションの方法については、[ページネーション](https://platform.claude.com/docs/ja/cli-sdks-libraries/sdks/java#pagination)を参照してください。 ## ファイルアップロード SDKは `MultipartField` クラスを通じてファイルを受け付けるメソッドを定義しています。 ```java import com.anthropic.core.MultipartField; import com.anthropic.models.files.FileMetadata; import com.anthropic.models.files.FileUploadParams; FileUploadParams params = FileUploadParams.builder() .file( MultipartField.builder() .value(Files.newInputStream(Paths.get("/path/to/file.pdf"))) .contentType("application/pdf") .build() ) .build(); FileMetadata fileMetadata = client.files().upload(params); ``` または `InputStream` から： ```java import com.anthropic.core.MultipartField; import com.anthropic.models.files.FileMetadata; import com.anthropic.models.files.FileUploadParams; FileUploadParams params = FileUploadParams.builder() .file( MultipartField.builder() .value(URI.create("https://example.com/path/to/file").toURL().openStream()) .filename("document.pdf") .contentType("application/pdf") .build() ) .build(); FileMetadata fileMetadata = client.files().upload(params); ``` またはメモリ内のバイトから： ```java import com.anthropic.core.MultipartField; import com.anthropic.models.files.FileMetadata; import com.anthropic.models.files.FileUploadParams; FileUploadParams params = FileUploadParams.builder() .file( MultipartField.builder() .value(new ByteArrayInputStream("content".getBytes())) .filename("document.txt") .contentType("text/plain") .build() ) .build(); FileMetadata fileMetadata = client.files().upload(params); ``` ### バイナリレスポンス SDKは、必ずしもJSONとしてパースされないAPIレスポンスに対してバイナリレスポンスを返すメソッドを定義しています。 ```java import com.anthropic.core.http.HttpResponse; HttpResponse response = client.files().download("file_abc123"); ``` レスポンスの内容をファイルに保存するには： ```java import com.anthropic.core.http.HttpResponse; try (HttpResponse response = client.files().download(params)) { Files.copy( response.body(), Paths.get(path), StandardCopyOption.REPLACE_EXISTING ); } catch (Exception e) { IO.println("Something went wrong!"); throw new RuntimeException(e); } ``` またはレスポンスの内容を任意の `OutputStream` に転送するには： ```java import com.anthropic.core.http.HttpResponse; try (HttpResponse response = client.files().download(params)) { response.body().transferTo(Files.newOutputStream(Paths.get(path))); } catch (Exception e) { IO.println("Something went wrong!"); throw new RuntimeException(e); } ``` ## エラー処理 SDKはカスタムの非チェック例外型をスローします。 * `AnthropicServiceException` - HTTPエラーの基底クラス。 * `AnthropicIoException` - I/Oネットワークエラー。 * `AnthropicRetryableException` - 再試行可能な失敗を示す汎用エラー。 * `AnthropicInvalidDataException` - 正常にパースされたデータの解釈の失敗（例えば、必須であるはずのプロパティにアクセスしたが、APIが予期せずそれを省略した場合）。 * `AnthropicException` - すべての例外の基底クラス。 ### ステータスコードのマッピング | ステータス | 例外 | | ----- | ------------------------------- | | 400 | `BadRequestException` | | 401 | `UnauthorizedException` | | 403 | `PermissionDeniedException` | | 404 | `NotFoundException` | | 422 | `UnprocessableEntityException` | | 429 | `RateLimitException` | | 5xx | `InternalServerException` | | その他 | `UnexpectedStatusCodeException` | `SseException` は、最初のHTTPレスポンスが成功した後のSSEストリーミング中に発生したエラーに対してスローされます。 ```java import com.anthropic.errors.*; try { Message message = client.messages().create(params); } catch (RateLimitException e) { IO.println("Rate limited, retry after: " + e.headers()); } catch (UnauthorizedException e) { IO.println("Invalid API key"); } catch (AnthropicServiceException e) { IO.println("API error: " + e.statusCode()); } catch (AnthropicIoException e) { IO.println("Network error: " + e.getMessage()); } ``` ## リクエストID [生のレスポンス](https://platform.claude.com/docs/ja/cli-sdks-libraries/sdks/java#raw-response-access)を使用する場合、`requestId()` メソッドを使用して `request-id` レスポンスヘッダーにアクセスできます。 ```java import com.anthropic.core.http.HttpResponseFor; import com.anthropic.models.messages.Message; HttpResponseFor message = client.messages().withRawResponse().create(params); Optional requestId = message.requestId(); ``` これは、失敗したリクエストを素早くログに記録してAnthropicに報告するために使用できます。リクエストのデバッグの詳細については、[リクエストID](https://platform.claude.com/docs/ja/api/errors#request-id)を参照してください。 ## 再試行 SDKはデフォルトで自動的に2回再試行し、リクエスト間に短い指数バックオフを挟みます。 以下のエラータイプのみが再試行されます。 * 接続エラー（例えば、ネットワーク接続の問題によるもの） * 408 Request Timeout * 409 Conflict * 429 Rate Limit * 5xx Internal APIは、リクエストを再試行するかしないかをSDKに明示的に指示することもあります。 カスタムの再試行回数を設定するには、`maxRetries` メソッドを使用してクライアントを設定します。 ```java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; AnthropicClient client = AnthropicOkHttpClient.builder().fromEnv().maxRetries(4).build(); ``` ## タイムアウト リクエストはデフォルトで10分後にタイムアウトします。 ただし、`maxTokens` を受け付けるメソッドでは、大きな `maxTokens` 値を指定してストリーミングしている場合、デフォルトのタイムアウトは次の式を使用して動的に計算されます。 ```java Duration.ofSeconds( Math.min( 60 * 60, // 1 hour max Math.max( 10 * 60, // 10 minute minimum 60 * 60 * maxTokens / 128_000 ) ) ) ``` これにより、上書きされない限り、`maxTokens` パラメータに応じてスケールされた最大60分のタイムアウトになります。 非ストリーミングリクエストの場合、動的タイムアウトは `maxTokens` に基づいて最小30秒から最大10分までスケールします。 リクエストごとにカスタムタイムアウトを設定するには： ```java import com.anthropic.models.messages.Message; Message message = client .messages() .create(params, RequestOptions.builder().timeout(Duration.ofSeconds(30)).build()); ``` またはクライアントレベルですべてのメソッド呼び出しのデフォルトを設定するには： ```java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; AnthropicClient client = AnthropicOkHttpClient.builder() .fromEnv() .timeout(Duration.ofSeconds(30)) .build(); ``` ## 長時間のリクエスト 長時間実行されるリクエストには[ストリーミング](https://platform.claude.com/docs/ja/cli-sdks-libraries/sdks/java#streaming)の使用を検討してください。 ストリーミングを使用せずに大きな `maxTokens` 値を設定することは避けてください。一部のネットワークでは、一定時間後にアイドル接続が切断されることがあり、Anthropicからレスポンスを受信しないままリクエストが失敗したり[タイムアウト](https://platform.claude.com/docs/ja/cli-sdks-libraries/sdks/java#timeouts)したりする原因となります。SDKは接続を維持し、これらのネットワークの影響を軽減するために、定期的にAPIにpingを送信します。 非ストリーミングリクエストが10分以上かかると予想される場合、SDKはエラーをスローします。[ストリーミングメソッド](https://platform.claude.com/docs/ja/cli-sdks-libraries/sdks/java#streaming)を使用するか、クライアントまたはリクエストレベルで[タイムアウトを上書き](https://platform.claude.com/docs/ja/cli-sdks-libraries/sdks/java#timeouts)すると、このエラーは無効になります。 ## ページネーション SDKは、ページネーションされた結果に、1ページずつ、またはすべてのページにわたって項目ごとにアクセスする便利な方法を提供します。 ### 自動ページネーション すべてのページにわたってすべての結果を反復処理するには、必要に応じて自動的に追加のページを取得する `autoPager()` メソッドを使用します。 ```java import com.anthropic.models.messages.batches.BatchListPage; import com.anthropic.models.messages.batches.MessageBatch; BatchListPage page = client.messages().batches().list(); // Iterableとして処理する for (MessageBatch batch : page.autoPager()) { IO.println(batch); } // Streamとして処理する page.autoPager() .stream() .limit(50) .forEach(batch -> IO.println(batch)); ``` 非同期クライアントを使用する場合、メソッドは `AsyncStreamResponse` を返します。 ```java import com.anthropic.core.http.AsyncStreamResponse; import com.anthropic.models.messages.batches.BatchListPageAsync; import com.anthropic.models.messages.batches.MessageBatch; CompletableFuture pageFuture = client.async().messages().batches().list(); pageFuture.thenAccept(page -> page.autoPager().subscribe(batch -> { IO.println(batch); })); // ストリームのエラーや完了を処理する必要がある場合 pageFuture.thenAccept(page -> page.autoPager().subscribe(new AsyncStreamResponse.Handler<>() { @Override public void onNext(MessageBatch batch) { IO.println(batch); } @Override public void onComplete(Optional error) { if (error.isPresent()) { IO.println("Something went wrong!"); throw new RuntimeException(error.get()); } else { IO.println("No more!"); } } })); // または futures を使用 pageFuture.thenAccept(page -> page.autoPager() .subscribe(batch -> { IO.println(batch); }) .onCompleteFuture() .whenComplete((unused, error) -> { if (error != null) { IO.println("Something went wrong!"); throw new RuntimeException(error); } else { IO.println("No more!"); } })); ``` ### 手動ページネーション 個々のページ項目にアクセスし、次のページを手動でリクエストするには： ```java import com.anthropic.models.messages.batches.BatchListPage; import com.anthropic.models.messages.batches.MessageBatch; BatchListPage page = client.messages().batches().list(); while (true) { for (MessageBatch batch : page.items()) { IO.println(batch); } if (!page.hasNextPage()) { break; } page = page.nextPage(); } ``` ## 型システム ### 不変性とビルダー SDKの各クラスには、それを構築するための関連ビルダーがあります。各クラスは構築後は不変です。クラスに関連ビルダーがある場合、そのクラスには `toBuilder()` メソッドがあり、変更されたコピーを作成するためにビルダーに戻すことができます。 ```java MessageCreateParams params = MessageCreateParams.builder() .maxTokens(1024L) .addUserMessage("Hello, Claude") .model(Model.CLAUDE_OPUS_5_5) .build(); // toBuilder() を使用して変更したコピーを作成します MessageCreateParams modified = params.toBuilder().maxTokens(2048L).build(); ``` 各クラスは不変であるため、ビルダーの変更がすでに構築されたクラスインスタンスに影響することはありません。 ### リクエストとレスポンス Claude APIにリクエストを送信するには、何らかの `Params` クラスのインスタンスを構築し、対応するクライアントメソッドに渡します。レスポンスを受信すると、Javaクラスのインスタンスにデシリアライズされます。 例えば、`client.messages().create(...)` は `MessageCreateParams` のインスタンスで呼び出す必要があり、`Message` のインスタンスを返します。 ### ドキュメント化されていないパラメータ ドキュメント化されていないパラメータを設定するには、任意の `Params` クラスで `putAdditionalHeader`、`putAdditionalQueryParam`、または `putAdditionalBodyProperty` メソッドを呼び出します。 ```java import com.anthropic.core.JsonValue; import com.anthropic.models.messages.MessageCreateParams; MessageCreateParams params = MessageCreateParams.builder() .putAdditionalHeader("Secret-Header", "42") .putAdditionalQueryParam("secret_query_param", "42") .putAdditionalBodyProperty("secretProperty", JsonValue.from("42")) .build(); ``` これらは後で構築されたオブジェクト上で `_additionalHeaders()`、`_additionalQueryParams()`、`_additionalBodyProperties()` メソッドを使用してアクセスできます。 これらのメソッドに渡された値は、以前のメソッドに渡された値を上書きします。セキュリティ上の理由から、これらのメソッドは信頼できる入力データでのみ使用するようにしてください。 ネストされたヘッダー、クエリパラメータ、またはボディクラスにドキュメント化されていないパラメータを設定するには： ```java import com.anthropic.core.JsonValue; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Metadata; MessageCreateParams params = MessageCreateParams.builder() .metadata( Metadata.builder().putAdditionalProperty("secretProperty", JsonValue.from("42")).build() ) .build(); ``` これらのプロパティは後でネストされた構築済みオブジェクト上で `_additionalProperties()` メソッドを使用してアクセスできます。 ドキュメント化されたパラメータまたはプロパティを、ドキュメント化されていない値やまだサポートされていない値に設定するには、そのセッターに `JsonValue` オブジェクトを渡します。 ```java import com.anthropic.core.JsonValue; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; MessageCreateParams params = MessageCreateParams.builder() .maxTokens(JsonValue.from(3.14)) .addUserMessage("Hello, Claude") .model(Model.CLAUDE_OPUS_5_5) .build(); ``` ### JsonValueの作成 `JsonValue` を作成する最も簡単な方法は、その `from(...)` メソッドを使用することです。 ```java import com.anthropic.core.JsonValue; // プリミティブなJSON値を作成 JsonValue nullValue = JsonValue.from(null); JsonValue booleanValue = JsonValue.from(true); JsonValue numberValue = JsonValue.from(42); JsonValue stringValue = JsonValue.from("Hello World!"); // `["Hello", "World"]` と同等のJSON配列値を作成 JsonValue arrayValue = JsonValue.from(List.of("Hello", "World")); // `{ "a": 1, "b": 2 }` と同等のJSONオブジェクト値を作成 JsonValue objectValue = JsonValue.from(Map.of("a", 1, "b", 2)); // 以下と同等の任意にネストされたJSONを作成: // { "a": [1, 2], "b": [3, 4] } JsonValue complexValue = JsonValue.from(Map.of("a", List.of(1, 2), "b", List.of(3, 4))); ``` ### 必須パラメータの強制的な省略 通常、`Builder` クラスの `build` メソッドは、必須のパラメータまたはプロパティが未設定の場合に `IllegalStateException` をスローします。必須のパラメータまたはプロパティを強制的に省略するには、`JsonMissing` を渡します。 ```java import com.anthropic.core.JsonMissing; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; MessageCreateParams params = MessageCreateParams.builder() .addUserMessage("Hello, world") .model(Model.CLAUDE_OPUS_5_5) .maxTokens(JsonMissing.of()) .build(); ``` ### レスポンスプロパティ ドキュメント化されていないレスポンスプロパティにアクセスするには、`_additionalProperties()` メソッドを呼び出します。 ```java import com.anthropic.core.JsonValue; Map additionalProperties = client .messages() .create(params) ._additionalProperties(); JsonValue secretPropertyValue = additionalProperties.get("secretProperty"); String result = secretPropertyValue.accept(new JsonValue.Visitor<>() { @Override public String visitNull() { return "It's null!"; } @Override public String visitBoolean(boolean value) { return "It's a boolean!"; } @Override public String visitNumber(Number value) { return "It's a number!"; } // 他のメソッドには `visitMissing`、`visitString`、`visitArray`、`visitObject` があります // 未実装の各メソッドのデフォルト実装は `visitDefault` に委譲します。 // `visitDefault` はデフォルトで例外をスローしますが、オーバーライドも可能です }); ``` プロパティの生のJSON値にアクセスするには、`_` プレフィックス付きのメソッドを呼び出します。 ```java import com.anthropic.core.JsonField; import com.anthropic.models.messages.StopReason; JsonField stopReason = client.messages().create(params)._stopReason(); if (stopReason.isMissing()) { // プロパティがJSONレスポンスに存在しない } else if (stopReason.isNull()) { // プロパティがリテラルのnullに設定されていた } else { // 値が文字列として提供されたかどうかを確認 // 他のメソッドには `asNumber()`、`asBoolean()` などがあります Optional jsonString = stopReason.asString(); // カスタム型へのデシリアライズを試みる MyClass myObject = stopReason.asUnknown().orElseThrow().convert(MyClass.class); } ``` ### レスポンス検証 デフォルトでは、APIが期待される型と一致しないレスポンスを返しても、SDKは例外をスローしません。プロパティに直接アクセスした場合にのみ `AnthropicInvalidDataException` をスローします。 レスポンスが完全に正しく型付けされていることを事前に確認するには、`validate()` を呼び出します。 ```java import com.anthropic.models.messages.Message; Message message = client.messages().create(params).validate(); ``` またはリクエストごとに設定します。 ```java import com.anthropic.models.messages.Message; Message message = client .messages() .create(params, RequestOptions.builder().responseValidation(true).build()); ``` またはクライアントレベルですべてのメソッド呼び出しのデフォルトを設定します。 ```java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; AnthropicClient client = AnthropicOkHttpClient.builder() .fromEnv() .responseValidation(true) .build(); ``` ## HTTPクライアントのカスタマイズ ### プロキシ設定 ```java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import java.net.Proxy; AnthropicClient client = AnthropicOkHttpClient.builder() .fromEnv() .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("https://example.com", 8080))) .build(); ``` ### HTTPS / SSL設定 ほとんどのアプリケーションはこれらのメソッドを呼び出すべきではなく、代わりにシステムのデフォルトを使用してください。デフォルトには、実装を変更すると失われる可能性のある特別な最適化が含まれています。 ```java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; AnthropicClient client = AnthropicOkHttpClient.builder() .fromEnv() .sslSocketFactory(yourSSLSocketFactory) .trustManager(yourTrustManager) .hostnameVerifier(yourHostnameVerifier) .build(); ``` ### カスタムHTTPクライアント SDKは3つのアーティファクトで構成されています。 * `anthropic-java-core` - コアSDKロジックを含み、OkHttpに依存しません。`AnthropicClient`、`AnthropicClientAsync`、およびそれらの実装クラスを公開しており、これらはすべて任意のHTTPクライアントで動作します。 * `anthropic-java-client-okhttp` - OkHttpに依存します。`AnthropicOkHttpClient` と `AnthropicOkHttpClientAsync` を公開します。 * `anthropic-java` - `anthropic-java-core` と `anthropic-java-client-okhttp` の両方に依存し、それらのAPIを公開します。独自のロジックは持ちません。 この構造により、不要な依存関係を取り込むことなく、SDKのデフォルトHTTPクライアントを置き換えることができます。 #### カスタマイズされたOkHttpClient デフォルトクライアントを置き換える前に、利用可能な[ネットワークオプション](https://platform.claude.com/docs/ja/cli-sdks-libraries/sdks/java#retries)を試してください。 カスタマイズされた `OkHttpClient` を使用するには： 1. `anthropic-java` の依存関係を `anthropic-java-core` に置き換えます。 2. `anthropic-java-client-okhttp` の `OkHttpClient` クラスをコードにコピーしてカスタマイズします。 3. カスタマイズしたクライアントを使用して `AnthropicClientImpl` または `AnthropicClientAsyncImpl` を構築します。 #### 完全にカスタムなHTTPクライアント 完全にカスタムなHTTPクライアントを使用するには： 1. `anthropic-java` の依存関係を `anthropic-java-core` に置き換えます。 2. `HttpClient` インターフェースを実装するクラスを作成します。 3. 新しいクライアントクラスを使用して `AnthropicClientImpl` または `AnthropicClientAsyncImpl` を構築します。 ## プラットフォーム統合 コード例を含む詳細なプラットフォームセットアップガイドについては、以下を参照してください。 * [Amazon Bedrock](https://platform.claude.com/docs/ja/build-with-claude/claude-in-amazon-bedrock) * [Amazon Bedrock（Opus 4.6以前）](https://platform.claude.com/docs/ja/build-with-claude/claude-on-amazon-bedrock-legacy) * [Claude Platform on AWS](https://platform.claude.com/docs/ja/build-with-claude/claude-platform-on-aws) * [Google Cloud](https://platform.claude.com/docs/ja/build-with-claude/claude-on-vertex-ai) * [Microsoft Foundry](https://platform.claude.com/docs/ja/build-with-claude/claude-in-microsoft-foundry) Java SDKは、プラットフォーム固有の `Backend` 実装を提供する個別の依存関係を通じて、以下のプラットフォームをサポートしています。 * **Agent Platform:** `com.anthropic:anthropic-java-vertex`：`VertexBackend.builder()` または `VertexBackend.fromEnv()` を使用します。`fromEnv()` は `CLOUD_ML_REGION` と `ANTHROPIC_VERTEX_PROJECT_ID` を読み取り、Application Default Credentialsを使用します。 * **Bedrock:** `com.anthropic:anthropic-java-bedrock`：Messages-API Bedrockエンドポイントには `BedrockMantleBackend.fromEnv()` または `BedrockMantleBackend.builder()` を使用し、または `BedrockBackend.fromEnv()` / `BedrockBackend.builder()`（`bedrock-runtime` パス）を使用します。 * **Claude Platform on AWS:** `com.anthropic:anthropic-java-aws`：`AwsBackend.fromEnv()`（`ANTHROPIC_AWS_WORKSPACE_ID` とAWSのデフォルトリージョン/認証情報チェーンを読み取ります）または `AwsBackend.builder()` を使用します。ベータ版で利用可能です。 * **Foundry:** `com.anthropic:anthropic-java-foundry`：`FoundryBackend.fromEnv()` または `FoundryBackend.builder()` を使用します。 新しいプロジェクトには `BedrockMantleBackend` を使用してください。`BedrockBackend` は、Bedrockの `InvokeModel` APIを使用する既存のアプリケーション向けに残されています。 プラットフォームアーティファクトは、`AnthropicOkHttpClient` を提供するベースの `com.anthropic:anthropic-java` 依存関係へのアドオンであるため、両方をインストールしてください。各 `Backend` 実装は、`AnthropicOkHttpClient.builder()` の `.backend()` でクライアントに渡されます。各クラウドバックエンドは、それぞれのクラウドプラットフォームSDKクラスを推移的依存関係として取り込みます。 ## 高度な使用方法 ### 生のレスポンスへのアクセス HTTPヘッダー、ステータスコード、および生のレスポンスボディにアクセスするには、任意のHTTPメソッド呼び出しの前に `withRawResponse()` を付けます。 ```java import com.anthropic.core.http.Headers; import com.anthropic.core.http.HttpResponseFor; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; MessageCreateParams params = MessageCreateParams.builder() .maxTokens(1024L) .addUserMessage("Hello, Claude") .model(Model.CLAUDE_OPUS_5_5) .build(); HttpResponseFor message = client.messages().withRawResponse().create(params); int statusCode = message.statusCode(); Headers headers = message.headers(); ``` 必要に応じて、レスポンスをJavaクラスのインスタンスにデシリアライズすることもできます。 ```java import com.anthropic.models.messages.Message; Message parsedMessage = message.parse(); ``` ### ロギング SDKは標準のOkHttpロギングインターセプターを使用します。 `ANTHROPIC_LOG` 環境変数を `info` に設定してロギングを有効にします。 ```bash export ANTHROPIC_LOG=info ``` またはより詳細なロギングのために `debug` に設定します。 ```bash export ANTHROPIC_LOG=debug ``` SDKはJSONのシリアライズ/デシリアライズにJacksonに依存しています。バージョン2.13.4以上と互換性がありますが、デフォルトではバージョン2.19.4に依存しています。 SDKは、実行時に互換性のないJacksonバージョンを検出した場合（例えば、MavenまたはGradleの設定でデフォルトバージョンが上書きされた場合）、例外をスローします。 SDKが例外をスローしたが、バージョンに互換性があると確信している場合は、`AnthropicOkHttpClient` または `AnthropicOkHttpClientAsync` の `checkJacksonVersionCompatibility` を使用してバージョンチェックを無効にしてください。 Jacksonのバージョンチェックが無効になっている場合、SDKが正しく動作する保証はありません。 また、古いJacksonバージョンにはSDKに影響を与える可能性のあるバグもあります。SDKはすべてのJacksonのバグを回避するわけではなく、それらについてはユーザーがJacksonをアップグレードすることを想定しています。 SDKはリフレクションを使用していますが、`anthropic-java-core` がkeepルールを含む設定ファイルとともに公開されているため、ProGuardおよびR8でも使用できます。 ProGuardとR8は公開されたルールを自動的に検出して使用するはずですが、必要に応じてkeepルールを手動でコピーすることもできます。 ### ドキュメント化されていないAPI機能 SDKはドキュメント化されたAPIを便利に使用できるように型付けされています。ただし、ドキュメント化されていない、またはまだサポートされていないAPIの部分を扱うこともサポートしています。 #### ドキュメント化されていないリクエストパラメータ ドキュメント化されていないリクエストパラメータを設定するには、[ドキュメント化されていないパラメータ](https://platform.claude.com/docs/ja/cli-sdks-libraries/sdks/java#undocumented-parameters)で説明されているように、`putAdditionalHeader`、`putAdditionalQueryParam`、または `putAdditionalBodyProperty` メソッドを使用します。 #### ドキュメント化されていないレスポンスプロパティ ドキュメント化されていないレスポンスプロパティにアクセスするには、[レスポンスプロパティ](https://platform.claude.com/docs/ja/cli-sdks-libraries/sdks/java#response-properties)で説明されているように、`_additionalProperties()` メソッドを使用します。 #### 新しいまたは未リリースのenum値 `Model` や `AnthropicBeta` などのSDK内のenumライクなクラスは、閉じたJavaの `enum` 型ではありません。それぞれが任意の文字列を受け付ける `of(String)` ファクトリメソッドを提供しているため、SDKバージョンより後にリリースされたモデルやベータヘッダーなど、まだSDKに追加されていない値を使用できます。 ```java import com.anthropic.models.beta.AnthropicBeta; import com.anthropic.models.messages.Model; Model model = Model.of("some-new-model"); AnthropicBeta beta = AnthropicBeta.of("some-new-beta-2026-01-01"); ``` これらの型を受け取るビルダーメソッドは、多くの場合、`of(...)` を代わりに呼び出す `String` オーバーロードも提供しています。 ```java import com.anthropic.models.messages.MessageCreateParams; MessageCreateParams params = MessageCreateParams.builder() .model("some-new-model") // same as .model(Model.of("some-new-model")) .maxTokens(1024L) .addUserMessage("Hello, Claude") .build(); ``` オートコンプリートと非推奨の警告が得られるように、正しく型付けされた定数（例：`Model.CLAUDE_OPUS_5`）を優先してください。`String` オーバーロードと `of(...)` は主に、それを含むSDKリリースを待つ間、フィールドをドキュメント化されていない値やまだサポートされていない値に設定するためのものです。 ## ベータ機能 ベータ機能は、早期のフィードバックを得て新機能をテストするために、正式リリース前に利用可能になります。Claudeのすべての機能とツールの利用可能状況は、[機能の概要](https://platform.claude.com/docs/ja/build-with-claude/overview)で確認できます。 ほとんどのベータAPI機能には、クライアントの `beta()` メソッドを通じてアクセスできます。特定のベータ機能を有効にするには、メッセージパラメータを構築する際に `.addBeta()` で適切な[ベータヘッダー](https://platform.claude.com/docs/ja/api/beta-headers)を追加します。 例えば、[コンテキスト編集](https://platform.claude.com/docs/ja/build-with-claude/context-editing)を有効にするには： ```java import com.anthropic.models.beta.AnthropicBeta; import com.anthropic.models.beta.messages.BetaMessage; import com.anthropic.models.beta.messages.MessageCreateParams; // ... void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); BetaMessage message = client.beta().messages().create( MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(1024L) .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27) .addUserMessage("Hello, Claude") .build()); } ``` ## よくある質問 Javaの `enum` クラスは、簡単には前方互換になりません。SDKでそれらを使用すると、APIが新しいenum値で応答するように更新された場合に実行時例外が発生する可能性があります。 これらのクラスは開いているため、`of(String)` ファクトリメソッドを通じて任意の文字列値で構築することもできます。SDKバージョンにまだ含まれていない値を使用する必要がある場合は、[新しいまたは未リリースのenum値](https://platform.claude.com/docs/ja/cli-sdks-libraries/sdks/java#new-or-unreleased-enum-values)を参照してください。 `JsonField` を使用すると、いくつかの機能が有効になります。 * ドキュメント化されていないAPI機能の使用を可能にする * 期待される形状に対してAPIレスポンスを遅延検証する * 存在しない値と明示的なnull値を区別して表現する データクラスに新しいフィールドを追加することは後方互換ではなく、SDKはクラスにフィールドが追加されるたびに破壊的変更を導入することを避けています。 チェック例外は、Javaプログラミング言語における誤りであると広く考えられています。実際、この理由からKotlinでは省略されました。 チェック例外は： * 処理が冗長である * エラーに対して何もできない、誤った抽象化レベルでのエラー処理を助長する * 関数カラーリング問題のために伝播が面倒である * ラムダとの相性が悪い（これも関数カラーリング問題のため） ## セマンティックバージョニング このパッケージは概ね[SemVer](https://semver.org/spec/v2.0.0.html)の規約に従っていますが、特定の後方互換性のない変更がマイナーバージョンとしてリリースされる場合があります。 1. 技術的にはpublicであるが、外部での使用を意図またはドキュメント化していないライブラリ内部への変更。 2. 実際には大多数のユーザーに影響を与えないと予想される変更。 ## 追加リソース * [GitHubリポジトリ](https://github.com/anthropics/anthropic-sdk-java) * [Javadocs](https://javadoc.io/doc/com.anthropic/anthropic-java) * [APIリファレンス](https://platform.claude.com/docs/ja/api/overview) * [メッセージのストリーミング](https://platform.claude.com/docs/ja/build-with-claude/streaming) * [Claudeでのツール使用](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/overview)