214 214
215### `upstreams`215### `upstreams`
216 216
217`upstreams` adalah daftar berurutan. Gateway meneruskan inferensi ke upstream pertama yang dapat me-resolve model yang diminta.217`upstreams` adalah daftar berurutan. Gateway meneruskan inferensi ke upstream pertama yang me-resolve model yang diminta, melewati upstream mana pun yang [daftar `groups`](#send-each-team-to-its-own-upstream)-nya tidak menyertakan developer tersebut.
218 218
219Pada `5xx`, `429`, `401`, `403`, `404`, atau timeout, gateway melakukan failover ke upstream berikutnya; `4xx` lainnya tidak, karena error tersebut disebabkan oleh permintaan, bukan oleh upstream. `401` atau `403` berarti upstream menolak kredensial yang digunakan gateway, atau menolak aksesnya, misalnya ke model yang diminta. `404` berarti upstream tersebut tidak melayani model yang diminta, sehingga upstream berikutnya dalam daftar masih dapat melayaninya.219Pada `5xx`, `429`, `401`, `403`, `404`, atau timeout, gateway melakukan failover ke upstream berikutnya; `4xx` lainnya tidak, karena error tersebut disebabkan oleh permintaan, bukan oleh upstream. `401` atau `403` berarti upstream menolak kredensial yang digunakan gateway, atau menolak aksesnya, misalnya ke model yang diminta. `404` berarti upstream tersebut tidak melayani model yang diminta, sehingga upstream berikutnya dalam daftar masih dapat melayaninya.
220 220
231Gateway mengembalikan respons error dari satu upstream, atau `502` miliknya sendiri, bergantung pada bagaimana upstream menjawab:231Gateway mengembalikan respons error dari satu upstream, atau `502` miliknya sendiri, bergantung pada bagaimana upstream menjawab:
232 232
233* **Sebuah upstream mengembalikan status yang tidak memicu [failover](#multiple-upstreams) oleh gateway**: respons upstream tersebut. Gateway tidak mencoba upstream lain.233* **Sebuah upstream mengembalikan status yang tidak memicu [failover](#multiple-upstreams) oleh gateway**: respons upstream tersebut. Gateway tidak mencoba upstream lain.
234* **Setiap upstream yang dicoba gateway gagal dengan cara yang [memicu failover](#multiple-upstreams)**: `429` terakhir. Ketika tidak ada yang mengembalikan `429`, gateway mengutamakan, secara berurutan, `401` atau `403` terakhir, `404` terakhir, dan `501` terakhir. Ketika tidak ada yang mengembalikan salah satu dari itu, `502` milik gateway sendiri, `all upstreams failed (N attempted)`, di mana N menghitung setiap entri di [`upstreams`](#upstreams), termasuk entri yang dilewati gateway karena tidak melayani model yang diminta.234* **Setiap upstream yang dicoba gateway gagal dengan cara yang [memicu failover](#multiple-upstreams)**: `429` terakhir. Jika tidak ada yang mengembalikan `429`, gateway memprioritaskan, secara berurutan, `401` atau `403` terakhir, `404` terakhir, dan `501` terakhir. Jika tidak ada yang mengembalikan salah satu dari itu, `502` milik gateway sendiri, `all upstreams failed (N attempted)`. N menghitung entri [`upstreams`](#upstreams) Anda, termasuk yang dilewati, dikurangi entri mana pun yang daftar [`groups`](#send-each-team-to-its-own-upstream)-nya tidak menyertakan developer tersebut.
235 235
236Ketika gateway mengembalikan respons upstream, gateway mempertahankan kode status upstream. Apakah pesan upstream dipertahankan bergantung pada penyedia. Body error dari upstream Anthropic API sampai ke developer tanpa perubahan.236Ketika gateway mengembalikan respons upstream, gateway mempertahankan kode status upstream. Apakah pesan upstream dipertahankan bergantung pada penyedia. Body error dari upstream Anthropic API sampai ke developer tanpa perubahan.
237 237
361 # keep the quotes: a bare 1 fails at boot361 # keep the quotes: a bare 1 fails at boot
362```362```
363 363
364> [!WARNING]
365>
366> Gateway tidak mendukung input tag guardrail. Gateway tidak menambahkan guard content tag ke prompt, sehingga filter guardrail yang diterapkan Amazon Bedrock hanya pada input yang diberi tag tidak berjalan pada lalu lintas melalui gateway. Untuk filter mana yang bergantung pada input tag, lihat [input tags](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html) dalam dokumentasi Amazon Bedrock.
367
368Berikan juga `bedrock:ApplyGuardrail` pada guardrail kepada principal yang menandatangani permintaan upstream ini: principal AWS milik gateway, atau dengan [`assume_role`](#bedrock-in-another-aws-account) role yang disebutkan di `role_arn`.364Berikan juga `bedrock:ApplyGuardrail` pada guardrail kepada principal yang menandatangani permintaan upstream ini: principal AWS milik gateway, atau dengan [`assume_role`](#bedrock-in-another-aws-account) role yang disebutkan di `role_arn`.
369 365
370Atur `guardrail` pada setiap upstream `bedrock` atau tidak sama sekali. Gateway menolak untuk dimulai jika ada campuran, karena [failover](#multiple-upstreams) dapat mengirim permintaan ke upstream Bedrock yang tidak memiliki guardrail.366Atur `guardrail` pada setiap upstream `bedrock` atau tidak sama sekali. Gateway menolak untuk dimulai jika ada campuran, karena [failover](#multiple-upstreams) dapat mengirim permintaan ke upstream Bedrock yang tidak memiliki guardrail.
373 369
374Ketika permintaan `/v1/messages` yang body-nya membawa field `amazon-bedrock-*`, seperti `amazon-bedrock-guardrailConfig`, mencapai upstream Bedrock yang memiliki `guardrail`, gateway menjawab 400 alih-alih meneruskannya.370Ketika permintaan `/v1/messages` yang body-nya membawa field `amazon-bedrock-*`, seperti `amazon-bedrock-guardrailConfig`, mencapai upstream Bedrock yang memiliki `guardrail`, gateway menjawab 400 alih-alih meneruskannya.
375 371
372> [!WARNING]
373>
374> Secara default gateway tidak menambahkan tag input ke prompt, sehingga filter guardrail yang diterapkan Amazon Bedrock hanya pada input bertag tidak berjalan pada lalu lintas melalui gateway. Untuk menambahkan tag, atur [`input_tagging`](#add-guardrail-input-tags). Untuk filter mana yang bergantung pada tag input, lihat [input tags](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html) di dokumentasi Amazon Bedrock.
375
376##### Menambahkan tag input guardrail
377
378Agar gateway menambahkan tag input yang dibutuhkan [filter prompt attacks](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-prompt-attack.html) pada guardrail Amazon Bedrock, atur `input_tagging` di blok `guardrail` dan mulai ulang gateway. Atur nilai yang sama pada setiap upstream `bedrock`, atau gateway menolak untuk dimulai. Memerlukan Claude Code v2.1.316 atau yang lebih baru di server gateway. Gateway pada versi yang tidak memiliki key ini keluar saat startup dengan `Unrecognized key(s) in object: 'input_tagging'`.
379
380> [!WARNING]
381>
382> Menurut [dokumentasi Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html), setiap filter dalam guardrail berhenti mengevaluasi konten tanpa tag begitu permintaan membawa tag input. Coba `input_tagging` pada gateway uji sebelum Anda mengaturnya pada gateway yang digunakan developer.
383
384`input_tagging` menerima salah satu nilai berikut:
385
386| `input_tagging` | Tempat gateway menandai teks | Setelah guardrail memblokir prompt |
387| :- | :- | :- |
388| `last_message` | Pesan `user` sejak balasan terakhir Claude | Di Claude Code, prompt berikutnya dapat lolos, dan Claude kemudian menerima prompt yang diblokir sebagai bagian dari percakapan |
389| `user_messages` | Pesan `user` | Prompt berikutnya dalam sesi juga dapat diblokir, hingga developer menghapus prompt yang diblokir |
390| `all_messages` | Pesan `user` dan `assistant` | Sama seperti `user_messages` |
391| `all_messages_and_system` | System prompt dan setiap pesan, termasuk [pesan sistem di tengah percakapan](https://code.claude.com/docs/id/llm-gateway-protocol.md#feature-pass-through) | Sama seperti `user_messages` |
392
393Dengan `last_message`, jika pesan `user` sejak balasan terakhir Claude tidak berisi teks untuk ditandai, gateway menandai pesan sistem di tengah percakapan sejak balasan tersebut. Panggilan tool dihitung sebagai balasan.
394
395Panduan Amazon Bedrock untuk filter prompt attacks adalah [menandai input pengguna sehingga system prompt dikecualikan](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-prompt-attack.html). Jika Anda mengatur `all_messages_and_system`, filter yang menandai system prompt Claude Code sendiri dapat memblokir permintaan.
396
397Contoh di bawah menandai teks di setiap pesan `user`:
398
399```yaml theme={null}
400upstreams:
401 - provider: bedrock
402 region: us-east-1
403 auth: {}
404 guardrail:
405 id: gr-abc123
406 version: "1"
407 input_tagging: user_messages
408```
409
410Pesan `user` juga dapat berisi teks yang ditambahkan Claude Code, seperti [system reminder](https://code.claude.com/docs/id/glossary.md#system-reminder), jadi periksa di gateway uji bahwa permintaan biasa tidak diblokir.
411
412Dalam pengujian Anthropic, sesi yang ditandai mempertahankan pembacaan [prompt cache](https://code.claude.com/docs/id/prompt-caching.md) dari satu prompt ke prompt berikutnya, dan tag tidak menambahkan token input.
413
414##### Yang tidak dicakup tag input
415
416Tidak ada nilai `input_tagging` yang menghentikan developer yang dengan sengaja menempatkan teks di tempat yang tidak diberi tag. Jangan mengandalkan guardrail untuk mengevaluasi bagian-bagian permintaan berikut:
417
418* **Konten yang tidak ditandai gateway**: pesan yang tidak dicakup nilai `input_tagging` Anda, definisi tool, input panggilan tool, gambar, dan PDF, di antaranya. Kecuali Anda mengatur `all_messages_and_system`, system prompt juga tidak ditandai.
419* **Hasil tool**: berisi apa yang dikembalikan tool Claude, seperti isi file dan halaman web. Dalam pengujian Anthropic, filter kata tidak mengevaluasinya, dengan atau tanpa tag.
420
421Jika akun atau organisasi AWS Anda memberlakukan guardrail, lihat [dokumentasi Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-enforcements.html) untuk cara guardrail tersebut memperlakukan tag input.
422
423##### Mencatat filter guardrail mana yang terpicu
424
425Untuk mengetahui filter guardrail Amazon Bedrock mana yang memblokir permintaan developer, atur `guardrail_trace: true` pada upstream Bedrock, restart gateway, dan minta developer mengirim permintaan lagi. Kemudian temukan event `guardrail.trace` permintaan tersebut di [log audit](https://code.claude.com/docs/id/claude-apps-gateway-deploy.md#logs). Memerlukan Claude Code v2.1.314 atau yang lebih baru di server gateway. Gateway yang lebih lama menolak untuk mulai saat menemukan `guardrail_trace`.
426
427```yaml theme={null}
428upstreams:
429 - provider: bedrock
430 region: us-east-1
431 auth: {}
432 guardrail:
433 id: gr-abc123
434 version: "1"
435 guardrail_trace: true # default false; beside guardrail, not inside it
436```
437
438Gateway menulis event `guardrail.trace`, tanpa teks yang cocok, saat filter terpicu atau tindakan guardrail adalah `INTERVENED`. Temukan event developer berdasarkan `email` atau `sub`. Satu permintaan streaming dapat menghasilkan beberapa event, dan salah satunya dapat memiliki daftar `filters` kosong, jadi baca setiap event yang memiliki `request_id` yang sama:
439
440| Field | Isinya |
441| - | - |
442| `request_id` | ID permintaan |
443| `sub`, `email` | ID pengguna dan email developer |
444| `upstream` | Upstream asal balasan |
445| `action` | Tindakan guardrail, seperti `INTERVENED` |
446| `filters` | Filter yang terpicu. Daftar kosong jika AWS tidak mengirimkan detail filter |
447| `filters[].side` | `input` atau `output` |
448| `filters[].guardrail` | ID guardrail |
449| `filters[].policy` | Kebijakan dan daftar Bedrock, seperti `contentPolicy.filters` atau `sensitiveInformationPolicy.piiEntities` |
450| Field `filters[]` lainnya | Entri juga dapat membawa field seperti `action`, `name`, `type`, `confidence`, `filterStrength`, `score`, dan `threshold` |
451
452Event tidak menyertakan teks yang dicocokkan filter, termasuk field `match` dari trace Bedrock. Developer tidak menerima data trace Bedrock, karena gateway menghapusnya dari setiap balasan, baik streaming maupun tidak.
453
454Jika klien mengirim field `amazon-bedrock-*` dalam body permintaan `/v1/messages`, gateway menjawab 400 pada upstream yang mengatur `guardrail_trace`.
455
376##### Bedrock di akun AWS lain456##### Bedrock di akun AWS lain
377 457
378Atur `assume_role` pada upstream Bedrock dan gateway menggunakan identitas AWS-nya sendiri hanya untuk memanggil `sts:AssumeRole` pada role yang Anda sebutkan, yang dapat berada di akun AWS yang berbeda dari gateway. Setiap permintaan Bedrock dari upstream tersebut ditandatangani dengan kredensial satu jam yang dikembalikan STS, sehingga tidak ada access key berumur panjang yang melintasi akun.458Atur `assume_role` pada upstream Bedrock dan gateway menggunakan identitas AWS-nya sendiri hanya untuk memanggil `sts:AssumeRole` pada role yang Anda sebutkan, yang dapat berada di akun AWS yang berbeda dari gateway. Setiap permintaan Bedrock dari upstream tersebut ditandatangani dengan kredensial satu jam yang dikembalikan STS, sehingga tidak ada access key berumur panjang yang melintasi akun.
415* Jika STS menolak atau tidak dapat dijangkau, gateway tidak mengirim permintaan dengan kredensial milik upstream sendiri. Gateway mencatat error STS beserta apa yang perlu diperiksa, lalu mencoba upstream berikutnya yang Anda cantumkan. [Pesan error upstream](#upstream-error-messages) menjelaskan apa yang diterima klien ketika tidak ada upstream yang berhasil. Upstream berikutnya tanpa `assume_role` akan melayani permintaan dengan kredensialnya sendiri, jadi cantumkan upstream seperti itu hanya jika memang itu yang Anda inginkan.495* Jika STS menolak atau tidak dapat dijangkau, gateway tidak mengirim permintaan dengan kredensial milik upstream sendiri. Gateway mencatat error STS beserta apa yang perlu diperiksa, lalu mencoba upstream berikutnya yang Anda cantumkan. [Pesan error upstream](#upstream-error-messages) menjelaskan apa yang diterima klien ketika tidak ada upstream yang berhasil. Upstream berikutnya tanpa `assume_role` akan melayani permintaan dengan kredensialnya sendiri, jadi cantumkan upstream seperti itu hanya jika memang itu yang Anda inginkan.
416* Gateway memanggil endpoint STS regional `sts.<region>.amazonaws.com`, yang harus dapat dijangkau jaringannya. Untuk endpoint FIPS, atur `AWS_USE_FIPS_ENDPOINT=true` di lingkungan gateway alih-alih `use_fips_endpoint` di file konfigurasi AWS.496* Gateway memanggil endpoint STS regional `sts.<region>.amazonaws.com`, yang harus dapat dijangkau jaringannya. Untuk endpoint FIPS, atur `AWS_USE_FIPS_ENDPOINT=true` di lingkungan gateway alih-alih `use_fips_endpoint` di file konfigurasi AWS.
417* `assume_role` hanya berlaku untuk `provider: bedrock` dan memerlukan kredensial sumber SigV4: gateway menolak untuk dimulai ketika diatur bersama `aws_bearer_token`.497* `assume_role` hanya berlaku untuk `provider: bedrock` dan memerlukan kredensial sumber SigV4: gateway menolak untuk dimulai ketika diatur bersama `aws_bearer_token`.
418* Setiap developer yang diterima gateway dapat menggunakan upstream ini; [`managed`](#managed) mengatur developer mana yang boleh menggunakan model mana. Agar model yang dilayani melalui role ini tidak juga dilayani dari akun lain, berikan model tersebut id kustom yang map `upstream_model`-nya hanya berisi nama upstream ini. Untuk id seperti itu gateway melewati setiap upstream lain, sehingga baik permintaan maupun penghitungan token untuk permintaan yang dibatalkan tidak dapat failover ke akun lain. Permintaan untuk nama model bawaan masih dapat [mencapai upstream ini](#multiple-upstreams), dan gateway menandatanganinya dengan role yang sama. Cantumkan upstream ini paling akhir kecuali akunnya juga harus melayani model-model tersebut.498* Tanpa [daftar `groups`](#send-each-team-to-its-own-upstream), setiap developer yang diizinkan gateway dapat menggunakan upstream ini. Untuk membatasi model mana yang dapat digunakan developer, atur `availableModels` dalam kebijakan [`managed`](#managed).
499* Agar model yang dilayani melalui role tersebut tidak juga dilayani dari akun lain, berikan id kustom yang peta `upstream_model`-nya hanya berisi nama upstream ini. Untuk id seperti itu, gateway melewati setiap upstream lain, sehingga baik permintaan maupun penghitungan token untuk permintaan yang dibatalkan tidak dapat melakukan failover ke akun lain.
500* Permintaan untuk nama model bawaan masih dapat [mencapai upstream ini](#multiple-upstreams), dan gateway menandatanganinya dengan role yang sama. Cantumkan upstream ini paling akhir kecuali akunnya juga harus melayani model-model tersebut.
419 501
420Contoh ini memberi satu model id kustom yang hanya dilayani oleh upstream terisolasi:502Contoh ini memberi satu model id kustom yang hanya dilayani oleh upstream terisolasi:
421 503
627 709
628`429` adalah kapasitas per upstream, sehingga habisnya provisioned-throughput (PT) memicu failover ke on-demand. Jika Anda mengatur [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run) pada sebuah upstream, `429` untuk permintaan yang membawa email developer justru merupakan penolakan per pengguna dan tidak memicu failover.710`429` adalah kapasitas per upstream, sehingga habisnya provisioned-throughput (PT) memicu failover ke on-demand. Jika Anda mengatur [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run) pada sebuah upstream, `429` untuk permintaan yang membawa email developer justru merupakan penolakan per pengguna dan tidak memicu failover.
629 711
630Setiap permintaan dimulai dari upstream pertama. Sebuah permintaan mencapai upstream berikutnya hanya ketika setiap upstream sebelumnya telah gagal atau tidak melayani model yang diminta.712Sebuah permintaan melewati suatu upstream hanya dalam kasus-kasus berikut:
713
714* Upstream tersebut gagal
715* Upstream tersebut tidak melayani model yang diminta
716* Upstream tersebut memiliki [daftar `groups`](#send-each-team-to-its-own-upstream) yang tidak mencakup developer tersebut
631 717
632Gateway tidak menyimpan catatan upstream yang gagal, sehingga selama sebuah upstream mati, setiap permintaan yang mencapainya tetap mencobanya dan menunggu hingga gagal sebelum melanjutkan.718Gateway tidak menyimpan catatan upstream yang gagal, sehingga selama sebuah upstream mati, setiap permintaan yang mencapainya tetap mencobanya dan menunggu hingga gagal sebelum melanjutkan.
633 719
680| - | - |766| - | - |
681| Region berbeda | Satu upstream Amazon Bedrock per region, masing-masing dengan `region:` sendiri. Dengan [`auto_include_builtin_models: true`](#models) inference profile lintas region dirutekan secara otomatis; untuk deployment yang disematkan ke region gunakan blok `models:`. |767| Region berbeda | Satu upstream Amazon Bedrock per region, masing-masing dengan `region:` sendiri. Dengan [`auto_include_builtin_models: true`](#models) inference profile lintas region dirutekan secara otomatis; untuk deployment yang disematkan ke region gunakan blok `models:`. |
682| Akun berbeda | Satu upstream Amazon Bedrock per akun. Rantai default (`auth: {}`) menggunakan identitas pod; untuk akun kedua, tambahkan [`assume_role`](#bedrock-in-another-aws-account) untuk menjangkaunya dengan kredensial berumur pendek, atau atur kredensial eksplisit atau bearer token di `auth:`. |768| Akun berbeda | Satu upstream Amazon Bedrock per akun. Rantai default (`auth: {}`) menggunakan identitas pod; untuk akun kedua, tambahkan [`assume_role`](#bedrock-in-another-aws-account) untuk menjangkaunya dengan kredensial berumur pendek, atau atur kredensial eksplisit atau bearer token di `auth:`. |
769| Tim berbeda | Berikan daftar `groups` pada upstream setiap tim, sehingga hanya developer dalam grup IdP tersebut yang dapat menjangkaunya. Lihat [Kirim setiap tim ke upstream-nya sendiri](#send-each-team-to-its-own-upstream). |
683| Provisioned throughput | Petakan model ke ARN provisioned-throughput di `models:` untuk nama upstream tersebut. Upstream lain tetap menggunakan ID on-demand, sehingga kapasitas PT habis sebelum failover. |770| Provisioned throughput | Petakan model ke ARN provisioned-throughput di `models:` untuk nama upstream tersebut. Upstream lain tetap menggunakan ID on-demand, sehingga kapasitas PT habis sebelum failover. |
684| Endpoint VPC / FIPS | Atur `base_url:` pada upstream ke URL endpoint VPC atau endpoint FIPS Anda |771| Endpoint VPC / FIPS | Atur `base_url:` pada upstream ke URL endpoint VPC atau endpoint FIPS Anda |
685| Perutean yang dibatasi per model | Hanya `id` model kustom, yaitu yang bukan model Claude bawaan, yang melewati upstream yang tidak ada di map `upstream_model:`-nya. Upstream `mantle` hanya dicoba untuk model yang tercantum di [field `models`](#amazon-bedrock-mantle-endpoint)-nya. Pada setiap upstream lainnya gateway mencoba model bawaan secara berurutan dan menggunakan ID default penyedia ketika map tidak memiliki entri, sehingga untuk model bawaan map mengubah ID mana yang diterima upstream alih-alih apakah upstream dicoba; upstream yang menolak ID tersebut mengikuti [aturan failover](#upstreams) yang sama seperti error upstream lainnya. |772| Perutean berbasis model | `id` model kustom, yaitu yang bukan model Claude bawaan, melewati upstream yang tidak ada dalam peta `upstream_model:`-nya. Upstream dengan daftar `models`, yang wajib dimiliki oleh [upstream `mantle`](#amazon-bedrock-mantle-endpoint), hanya dicoba untuk model-model tersebut. |
773| Perutean model bawaan | Pada upstream tanpa daftar `models` atau `groups`, gateway mencoba model bawaan secara berurutan dan menggunakan ID default penyedia jika peta `upstream_model:` tidak memiliki entri. Untuk model bawaan yang memiliki ID default dari penyedia, peta tersebut mengubah ID mana yang diterima upstream, bukan apakah upstream tersebut dicoba. Upstream yang menolak ID tersebut mengikuti [aturan failover](#upstreams) yang sama seperti error upstream lainnya. |
686 774
687Failover antar penyedia cloud, atau ke Anthropic API langsung, mengubah perjanjian, wilayah geografis, dan ketentuan lain yang mengatur permintaan tersebut.775Failover antar penyedia cloud, atau ke Anthropic API langsung, mengubah perjanjian, wilayah geografis, dan ketentuan lain yang mengatur permintaan tersebut.
688 776
689CLI menerapkan pembatasan fitur yang sama pada gateway terlepas dari upstream mana yang melayani permintaan tertentu, sehingga secara default failover tidak mengirim field body yang akan ditolak oleh upstream. Jika Anda mengatur [TTL cache satu jam](#one-hour-prompt-cache) dalam sebuah kebijakan, pengaturan tersebut dikirim ke setiap upstream dalam daftar, jadi atur hanya jika semua upstream menerimanya.777CLI menerapkan pembatasan fitur yang sama pada gateway terlepas dari upstream mana yang melayani permintaan tertentu, sehingga secara default failover tidak mengirim field body yang akan ditolak oleh upstream. Jika Anda mengatur [TTL cache satu jam](#one-hour-prompt-cache) dalam sebuah kebijakan, pengaturan tersebut dikirim ke setiap upstream dalam daftar, jadi atur hanya jika semua upstream menerimanya.
690 778
779#### Kirim setiap tim ke upstream-nya sendiri
780
781Untuk mengirim permintaan setiap tim ke akun AWS atau proyek Google Cloud-nya sendiri, cantumkan satu upstream per tim dan berikan masing-masing daftar `groups`. Hanya developer dalam grup IdP yang tercantum yang dapat menjangkau upstream tersebut, baik pada percobaan pertama maupun saat [failover](#multiple-upstreams). Setiap penyedia menerima `groups`. Memerlukan Claude Code v2.1.314 atau yang lebih baru pada server gateway.
782
783Contoh ini memberikan masing-masing satu akun AWS kepada grup `payments-eng` dan `search-eng`, serta menambahkan upstream tanpa daftar `groups` yang dapat digunakan oleh setiap developer:
784
785```yaml theme={null}
786upstreams:
787 - name: bedrock-payments
788 provider: bedrock
789 region: us-east-1
790 auth: {}
791 assume_role:
792 role_arn: arn:aws:iam::111111111111:role/claude-gateway-bedrock
793 groups: [payments-eng]
794 - name: bedrock-search
795 provider: bedrock
796 region: us-east-1
797 auth: {}
798 assume_role:
799 role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
800 groups: [search-eng]
801 - name: bedrock-shared # no groups: open to everyone, so listed last
802 provider: bedrock
803 region: us-east-1
804 auth: {}
805```
806
807Dengan konfigurasi contoh tersebut, permintaan setiap developer dimulai dari upstream pertama pada barisnya dan berpindah ke upstream berikutnya saat failover:
808
809| Grup developer | Upstream, secara berurutan |
810| - | - |
811| `payments-eng` | `bedrock-payments`, lalu `bedrock-shared` |
812| `search-eng` | `bedrock-search`, lalu `bedrock-shared` |
813| `payments-eng` dan `search-eng` | `bedrock-payments`, lalu `bedrock-search`, lalu `bedrock-shared` |
814| Tidak keduanya | `bedrock-shared` |
815
816Ketika upstream suatu tim menolak model yang diminta dengan `403`, gateway mencoba upstream berikutnya pada baris tim tersebut yang melayani model itu. Untuk mempertahankan tim pada satu upstream, berikan daftar `groups` pada setiap upstream, dan pastikan tidak ada upstream lain yang mencantumkan grup tempat developer tim tersebut berada. Tim tersebut kemudian tidak memiliki failover, dan permintaan dari developer yang tidak berada dalam grup mana pun yang tercantum akan [gagal dengan `400`](#what-happens-when-a-developer-is-in-no-listed-group).
817
818Agar setiap developer mencapai upstream yang Anda maksud, tulis entri yang cocok secara persis dan letakkan upstream terbuka di posisi terakhir:
819
820* **Entri**: tulis setiap grup persis seperti yang dikirim IdP Anda dalam [klaim groups](#oidc), yang juga dibaca oleh [`match.groups`](#managed). Gateway menolak untuk dimulai ketika menemukan daftar kosong atau entri kosong. Gateway tidak memeriksa entri terhadap IdP Anda, sehingga entri yang tidak cocok dengan siapa pun tidak memunculkan peringatan.
821* **Urutan**: letakkan upstream yang tidak memiliki daftar `groups` di posisi terakhir. Upstream tersebut melayani semua orang, sehingga jika dicantumkan lebih awal, upstream itu akan mengambil permintaan suatu tim sebelum upstream milik tim tersebut.
822
823> [!WARNING]
824>
825> Gateway yang lebih lama dari v2.1.314 menolak untuk dimulai ketika menemukan `groups`, jadi tingkatkan versi setiap replika sebelum Anda menambahkannya.
826>
827> Sebelum Anda melakukan rollback, hapus setiap upstream yang memiliki daftar `groups` beserta setiap kunci `upstream_model` atau override harga yang menyebutnya, dan pertahankan setidaknya satu upstream. Jika hanya kunci `groups` yang dihapus, upstream tersebut terbuka bagi setiap developer. Kunci atau override yang masih menyebut upstream yang telah dihapus akan mencegah gateway dimulai, dengan `references unknown upstream`.
828
829##### Apa yang terjadi ketika developer tidak berada dalam grup mana pun yang tercantum
830
831Jika setiap upstream memiliki daftar `groups`, developer yang tidak berada dalam grup mana pun tersebut akan melihat error ini, dan gateway tidak menghubungi penyedia mana pun:
832
833```text theme={null}
834API Error: 400 you aren't in a group that can use this gateway. Ask your administrator to add you to one
835```
836
837Tambahkan developer tersebut ke grup yang tercantum di IdP Anda, atau tambahkan upstream tanpa daftar `groups`.
838
839Gateway membaca ulang grup developer pada setiap refresh token. Jika IdP Anda tidak menyertakan grup dalam refresh, developer tersebut kemudian tidak memiliki grup:
840
841* **[`oidc.allowed_groups`](#oidc) diatur**: gateway menolak refresh, dan sesi berakhir
842* **Jika tidak, dan ada upstream tanpa daftar `groups`**: permintaan developer berpindah ke upstream tersebut
843* **Jika tidak, dan setiap upstream memiliki daftar `groups`**: permintaan developer gagal dengan error tersebut
844
845Jika endpoint userinfo IdP Anda mengembalikan klaim groups dan `oidc.google_groups` tidak diatur, atur [`oidc.userinfo_fallback`](#oidc) ke `true` untuk mengisi grup dari sana.
846
691## Bagian opsional847## Bagian opsional
692 848
693### `admin`849### `admin`
782 938
783#### Mengirim tarif ke klien yang sudah masuk939#### Mengirim tarif ke klien yang sudah masuk
784 940
785Dengan v2.1.268 atau yang lebih baru di server gateway, gateway juga memasukkan tarif dari `pricing` ke dalam kebijakan [`managed`](#managed) yang dilayaninya, sebagai pengaturan terkelola [`modelPricing`](https://code.claude.com/docs/id/settings-reference#modelpricing). Developer yang cocok dengan suatu kebijakan kemudian melihat tarif `pricing` untuk upstream pertama yang melayani setiap ID model di `/usage`, baris status, dan OpenTelemetry. Developer yang tidak cocok dengan kebijakan apa pun tidak menerima pengaturan terkelola, sehingga angka mereka tetap pada harga daftar. Klien menerapkan pengaturan ini di Claude Code v2.1.242 atau yang lebih baru.941Dengan v2.1.268 atau yang lebih baru di server gateway, gateway juga memasukkan tarif dari `pricing` ke dalam kebijakan [`managed`](#managed) yang dilayaninya, sebagai pengaturan terkelola [`modelPricing`](https://code.claude.com/docs/id/settings-reference#modelpricing).
942
943Pengembang yang cocok dengan suatu kebijakan kemudian melihat tarif `pricing` di `/usage`, baris status, dan OpenTelemetry. Pengembang yang tidak cocok dengan kebijakan mana pun tidak menerima pengaturan terkelola, sehingga angka mereka tetap pada harga daftar. Klien menerapkan pengaturan ini di Claude Code v2.1.242 atau yang lebih baru.
786 944
787* Apa yang ditambahkan gateway: kecuali blok `cli` suatu kebijakan sudah menyetel `modelPricing`, gateway menambahkan `multiplier` dan, untuk setiap ID model yang dapat diminta klien, baris override dari upstream pertama yang melayani ID tersebut. Tarif yang hanya dikenakan oleh upstream failover tetap di gateway.945* Apa yang ditambahkan gateway: kecuali blok `cli` suatu kebijakan sudah menyetel `modelPricing`, gateway menambahkan `multiplier` dan, untuk setiap ID model yang dapat diminta klien, baris override dari upstream pertama yang melayani ID tersebut. Tarif yang hanya dikenakan oleh upstream failover tetap di gateway.
946* Upstream dengan [daftar `groups`](#send-each-team-to-its-own-upstream): ketika salah satunya merupakan upstream pertama yang melayani suatu ID model, gateway tidak menambahkan baris untuk ID tersebut. Pengembang kemudian melihat tarif Claude Code sendiri untuk ID tersebut, yaitu tarif standar model ketika Claude Code mengenali ID tersebut, dikalikan `multiplier`.
788* Mengecualikan satu kebijakan: setel `modelPricing` ke `{}` di blok `cli` kebijakan tersebut, dan developer-nya tetap pada harga daftar.947* Mengecualikan satu kebijakan: setel `modelPricing` ke `{}` di blok `cli` kebijakan tersebut, dan developer-nya tetap pada harga daftar.
789* Mempertahankan tarif milik kebijakan: kebijakan yang blok `cli`-nya menyetel `modelPricing` dengan `multiplier` atau `overrides` sendiri mempertahankan `modelPricing` tersebut secara utuh, dan gateway tidak menambahkan tarifnya sendiri ke dalamnya.948* Mempertahankan tarif milik kebijakan: kebijakan yang blok `cli`-nya menyetel `modelPricing` dengan `multiplier` atau `overrides` sendiri mempertahankan `modelPricing` tersebut secara utuh, dan gateway tidak menambahkan tarifnya sendiri ke dalamnya.
790 949
808 967
809### `managed`968### `managed`
810 969
811Blok `managed` mendefinisikan kebijakan akses berbasis peran yang didasarkan pada grup IdP atau domain email. Kebijakan dievaluasi secara berurutan; kecocokan pertama dipilih, lalu digabungkan ke dasar catch-all `match: {}`. Kebijakan dilayani per pengguna di `GET /managed/settings` dengan caching ETag/304.970Blok `managed` mendefinisikan kebijakan akses berbasis peran yang dikunci pada grup IdP atau domain email. Kebijakan dievaluasi secara berurutan; secara default kecocokan pertama yang dipilih, lalu digabungkan ke basis catch-all `match: {}`. Pengguna yang cocok dengan dua kebijakan peran hanya mendapatkan yang pertama, sehingga aturan deny dari kebijakan kedua tidak berlaku kecuali Anda [menerapkan setiap kebijakan yang cocok](#apply-every-matching-policy). Kebijakan dilayani per pengguna di `GET /managed/settings` dengan caching ETag/304.
812 971
813```yaml theme={null}972```yaml theme={null}
814managed:973managed:
849 1008
850Pengguna terautentikasi yang tidak cocok dengan kebijakan apa pun mendapatkan default gateway, yang berarti setiap model dalam katalog dan tanpa pengaturan terkelola. Tambahkan catch-all `match: {}` di akhir jika Anda menginginkan kebijakan default yang terjamin.1009Pengguna terautentikasi yang tidak cocok dengan kebijakan apa pun mendapatkan default gateway, yang berarti setiap model dalam katalog dan tanpa pengaturan terkelola. Tambahkan catch-all `match: {}` di akhir jika Anda menginginkan kebijakan default yang terjamin.
851 1010
1011Letakkan aturan deny di seluruh organisasi dalam kebijakan `match: {}`, karena aturan kebijakan grup hanya berlaku selama token pengguna membawa grup tersebut.
1012
852> [!NOTE]1013> [!NOTE]
853>1014>
854> Gateway tidak menyimpan direktori pengguna sendiri. Gateway mengotorisasi setiap permintaan dari token IdP pengguna, membaca keanggotaan grup dari klaim `groups` token dan mengevaluasi kebijakan terhadapnya. Tidak ada daftar pengguna untuk dienumerasi dan tidak ada akun untuk dibuat sebelumnya, dan karena itu tidak ada endpoint SCIM, karena tidak ada yang perlu disinkronkan oleh SCIM.1015> Gateway tidak menyimpan direktori pengguna sendiri. Gateway mengotorisasi setiap permintaan dari token IdP pengguna, membaca keanggotaan grup dari klaim `groups` token dan mengevaluasi kebijakan terhadapnya. Tidak ada daftar pengguna untuk dienumerasi dan tidak ada akun untuk dibuat sebelumnya, dan karena itu tidak ada endpoint SCIM, karena tidak ada yang perlu disinkronkan oleh SCIM.
862>1023>
863> Claude Desktop mengikuti [jadwalnya sendiri](#when-a-policy-change-reaches-claude-desktop).1024> Claude Desktop mengikuti [jadwalnya sendiri](#when-a-policy-change-reaches-claude-desktop).
864 1025
1026#### Menerapkan setiap kebijakan yang cocok
1027
1028Pengguna yang cocok dengan beberapa kebijakan peran hanya mendapatkan yang pertama kecuali Anda mengatur `policy_mode: layered` di samping `policies`. Dengan `layered`, setiap kebijakan yang cocok dengan pengguna berlaku, hingga kebijakan `match: {}` pertama.
1029
1030`policy_mode` memerlukan Claude Code v2.1.316 atau yang lebih baru di server gateway. Gateway pada versi yang tidak memilikinya menolak untuk mulai saat menemukan kunci tersebut. Tingkatkan setiap replika sebelum Anda menambahkan kunci, dan hapus kunci sebelum Anda melakukan rollback ke versi sebelumnya. Contoh ini memiliki satu grup yang kehilangan `WebFetch` dan satu grup yang mendapatkan Opus:
1031
1032```yaml theme={null}
1033managed:
1034 policy_mode: layered
1035 policies:
1036 - match: { groups: [no-web] }
1037 cli:
1038 permissions: { deny: ["WebFetch"] }
1039 - match: { groups: [opus-users] }
1040 cli:
1041 availableModels: [opus, sonnet]
1042 - match: {}
1043 cli:
1044 availableModels: [sonnet]
1045 enforceAvailableModels: true
1046```
1047
1048Tabel ini menunjukkan apa yang diterima pengguna yang berada di `no-web` dan `opus-users` dalam mode default, `first_match`, dan dalam `layered`.
1049
1050| Pengaturan | `first_match` | `layered` |
1051| - | - | - |
1052| `availableModels` | `sonnet` | `opus`, `sonnet` |
1053| `enforceAvailableModels` | `true` | `true` |
1054| `permissions.deny` | `WebFetch` | `WebFetch` |
1055
1056Gateway menggabungkan setiap kebijakan yang cocok ke kebijakan yang tercantum di bawahnya, dengan [aturan penggabungan](#managed) yang sama seperti lapisan basis:
1057
1058* **Allowlist, nilai tunggal, dan blok seperti `sandbox`**: masing-masing diambil secara utuh dari kebijakan cocok yang tercantum pertama yang mengaturnya, sehingga daftar `availableModels` dari dua grup tidak dijumlahkan.
1059* **Daftar deny dan array hook**: ini dijumlahkan di seluruh kebijakan yang cocok, sehingga pengguna di dua grup mendapatkan aturan deny dari kedua grup.
1060* **`env`, `modelOverrides`, dan `skillOverrides`**: entri digabungkan berdasarkan nama, dan kebijakan cocok yang tercantum pertama yang mengatur suatu nama memberikan nilainya.
1061* **Kunci `desktop`**: ini digabungkan berdasarkan [aturan untuk blok `desktop` basis](#how-a-role-policy-inherits-the-base-desktop-block).
1062
1063> [!WARNING]
1064>
1065> Kebijakan dapat dijumlahkan menjadi aturan yang lebih longgar daripada yang diberikan salah satunya saja. Misalnya, kebijakan `match: {}` mengatur `sandbox.enabled: true`, kebijakan satu grup mengatur `permissions.allow: ["Bash"]`, dan kebijakan grup lain mengatur `sandbox.enabled: false`. Pengguna di kedua grup menerima `Bash` yang diizinkan dengan sandbox nonaktif. Dalam kasus ini, cantumkan kebijakan yang mengizinkan `Bash` terlebih dahulu, dan salin seluruh blok `sandbox` dari kebijakan `match: {}` ke dalamnya.
1066
1067Dengan `layered`, gateway menolak untuk mulai pada beberapa pengaturan, termasuk yang berikut:
1068
1069* **Pola `!`**: [negasi `!`](https://code.claude.com/docs/id/permissions#special-characters-and-negation) dalam aturan `Read` atau `Edit` di daftar `permissions.deny` atau `permissions.ask` kebijakan mana pun, termasuk milik kebijakan `match: {}`
1070* **Batasan pada hook di luar catch-all**: `disableAllHooks`, `allowedHttpHookUrls`, atau `httpHookAllowedEnvVars` di kebijakan mana pun selain `match: {}`
1071
865#### Memulai sesi pada model yang diizinkan kebijakan1072#### Memulai sesi pada model yang diizinkan kebijakan
866 1073
867Jika `availableModels` tidak menyertakan model default Claude Code, sesi mendapatkan respons `400` hingga developer memilih model yang tercantum, misalnya dengan `/model`. Dalam sesi gateway, default-nya adalah model Opus yang dituju alias `opus`, dan `availableModels` saja tidak mengubahnya.1074Jika `availableModels` tidak menyertakan model default Claude Code, sesi mendapatkan respons `400` hingga developer memilih model yang tercantum, misalnya dengan `/model`. Dalam sesi gateway, default-nya adalah model Opus yang dituju alias `opus`, dan `availableModels` saja tidak mengubahnya.
