Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Autentikasi Token Web JSON

Vector Search mendukung endpoint indeks yang diautentikasi menggunakan Token Web JSON (JWT) yang ditandatangani sendiri. Untuk mengontrol akses ke endpoint indeks, endpoint tersebut dikonfigurasi agar hanya menerima JWT bertanda tangan yang diterbitkan oleh akun layanan Google yang diizinkan secara khusus. Artinya, hanya klien yang menggunakan akun yang ditetapkan tersebut yang dapat berinteraksi dengan endpoint.

Halaman ini menguraikan langkah-langkah yang diperlukan untuk menyiapkan endpoint indeks dengan autentikasi Token Web JSON (JWT) dan menjalankan kueri terhadapnya.

Batasan

Autentikasi JWT hanya didukung untuk endpoint pribadi dengan peering VPC atau Private Service Connect (PSC).
Autentikasi JWT hanya didukung untuk RPC API data plane (seperti MatchService) yang dipanggil menggunakan gRPC. Contoh RPC di halaman ini menggunakan alat open source untuk mengirim permintaan gRPC ke server indeks yang di-deploy.grpc_cli
Admin API untuk pembuatan, deployment, dan pengelolaan indeks diamankan oleh menggunakan peran IAM bawaan.

Membuat dan menggunakan JWT untuk membuat kueri indeks

Ikuti langkah-langkah berikut untuk membuat endpoint indeks dan membuat kueri dengan JWT yang ditandatangani sendiri.

Membuat indeks

Buat indeks Penelusuran Vektor dengan mengikuti petunjuk di Membuat indeks.

Membuat endpoint pribadi

Buat endpoint pribadi dengan mengikuti petunjuk di salah satu halaman dokumentasi berikut:

Membuat akun layanan

Buat akun layanan dan berikan peran IAM Service Account Token Creator.

Aktifkan IAM Service Account Credentials API dan buat akun layanan:
```
gcloud services enable iamcredentials.googleapis.com --project="PROJECT_ID"
gcloud iam service-accounts create SERVICE_ACCOUNT_ID --project="PROJECT_ID"
```
Ganti nilai berikut:
- PROJECT_ID: Project tempat Anda akan membuat akun layanan.
- SERVICE_ACCOUNT_ID: ID untuk akun layanan.
Pelajari lebih lanjut tentang membuat akun layanan.
Gunakan salah satu perintah berikut untuk memberikan peran IAM iam.serviceAccountTokenCreator ke akun layanan Anda:
- Perintah berikut memberi Anda izin untuk membuat JWT menggunakan akun layanan dari VM Compute Engine yang memiliki akun layanan terlampir:
```
gcloud iam service-accounts add-iam-policy-binding \
   "SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
   --role "roles/iam.serviceAccountTokenCreator" \
   --member "serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
   --project "PROJECT_ID"
```
  Ganti nilai berikut:
  - SERVICE_ACCOUNT_ID: ID untuk akun layanan.
  - PROJECT_ID: Project tempat Anda akan membuat akun layanan.
- Perintah berikut memberikan izin untuk membuat JWT menggunakan akun layanan dari Akun Google Anda sendiri (di workstation Anda):
```
gcloud iam service-accounts add-iam-policy-binding \
   "SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
   --role "roles/iam.serviceAccountTokenCreator" \
   --member "user:EMAIL_ADDRESS" \
   --project PROJECT_ID
```
  Ganti nilai berikut:
  - SERVICE_ACCOUNT_ID: ID untuk akun layanan.
  - PROJECT_ID: Project tempat Anda akan membuat akun layanan.
  - EMAIL_ADDRESS: Alamat email Anda.

Men-deploy indeks ke endpoint dengan konfigurasi autentikasi JWT

Deploy indeks ke endpoint pribadi seperti yang ditunjukkan dalam contoh berikut:
```
gcloud ai index-endpoints deploy-index INDEX_ENDPOINT_ID \
   --index=INDEX_ID \
   --deployed-index-id=DEPLOYED_INDEX_ID \
   --display-name=DEPLOYED_INDEX_NAME \
   --audiences=AUDIENCES \
   --allowed-issuers="SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
   --project=PROJECT_ID \
   --region=LOCATION
```
Ganti nilai berikut:
- INDEX_ENDPOINT_ID: ID endpoint indeks.
- INDEX_ID: ID indeks.
- DEPLOYED_INDEX_ID: String yang ditentukan pengguna untuk mengidentifikasi indeks yang di-deploy secara unik. Nama ini harus diawali dengan huruf dan hanya berisi huruf, angka, atau garis bawah. Lihat DeployedIndex.id untuk panduan format.
- DEPLOYED_INDEX_NAME: Nama tampilan indeks yang di-deploy.
- AUDIENCES: String deskriptif yang mengidentifikasi audiens yang diharapkan untuk layanan, workload, atau aplikasi Anda, misalnya, "123456-my-app".
- SERVICE_ACCOUNT_ID: ID untuk akun layanan.
- PROJECT_ID: ID Google Cloud project Anda.
- LOCATION: Region tempat Anda menggunakan Agent Platform.

Membuat kueri indeks dengan JWT yang ditandatangani sendiri

Pada intinya, langkah-langkah yang diperlukan adalah sebagai berikut:

Buat payload JWT.
Tanda tangani token menggunakan akun layanan yang dibuat sebelumnya.
Buat kueri indeks menggunakan panggilan gRPC, dengan meneruskan token di header otorisasi.

Python

Membuat dan Menandatangani payload JWT

Contoh ini menggunakan metode sign_jwt library Kredensial IAM API Python untuk mendapatkan token yang ditandatangani. Untuk mempelajari lebih lanjut cara menginstal dan menggunakan library ini, lihat dokumentasi Library Klien IAM API.

   from google.cloud import iam_credentials_v1
   from datetime import datetime, timezone
   import json

   def sign_jwt(issuer: str, audience: str):
      client = iam_credentials_v1.IAMCredentialsClient()
      payload = {
            'aud': audience,
            'sub': audience,
            'iss': issuer,
            'iat': int(datetime.now(timezone.utc).timestamp()),
            'exp': int(datetime.now(timezone.utc).timestamp()) + 600,
      }
      response = client.sign_jwt(name="projects/-/serviceAccounts/" + issuer,
                                 payload=json.dumps(payload))
      return response.signed_jwt

   sign_jwt("SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com",
            "AUDIENCES")

Command-line

Membuat payload JWT

Autentikasi Vector Search menerima JWT yang ditandatangani dengan akun layanan yang telah diotorisasi sebelumnya, untuk audiens yang telah ditentukan. Akun layanan dan audiens harus ditentukan oleh pemanggil saat indeks di-deploy ke endpoint pribadi. Setelah indeks di-deploy dengan setelan ini, semua permintaan gRPC API ke endpoint tersebut harus menyertakan header otorisasi yang berisi JWT yang ditandatangani oleh penerbit (akun layanan) dan ditujukan ke audiens yang disediakan. JWT yang ditandatangani diteruskan sebagai token pembawa di header authorization permintaan gRPC. Selain ditandatangani oleh akun layanan, JWT harus menyertakan klaim berikut:

Klaim iss (penerbit yang diizinkan) harus berupa alamat email akun layanan, misalnya:
```
"iss": "SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com"
```
Klaim aud (audiens) dan sub (subjek) harus ditetapkan ke nilai yang sama. Ini adalah string deskriptif yang mengidentifikasi audiens yang diharapkan untuk layanan, workload, atau aplikasi Anda, misalnya:
```
"aud": "123456-my-app",
"sub": "123456-my-app"
```
Nilai ini harus cocok dengan argumen --audiences yang diteruskan pada waktu deployment indeks.
Klaim iat (diterbitkan pada) harus ditetapkan ke waktu token diterbitkan. Klaim exp (waktu habis masa berlaku) harus ditetapkan ke waktu singkat setelahnya (sekitar satu jam). Nilai ini dinyatakan dalam waktu epoch Unix, misalnya:
```
"iat": 1698966927, // unix time since epoch eg via date +%s
"exp": 1698967527 // iat + a few mins (eg 600 seconds)
```

Contoh berikut menunjukkan klaim ini dalam satu payload JWT:

{
   "iss": "SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com",
   "aud": "123456-my-app",
   "sub": "123456-my-app",
   "iat": 1698956084,
   "exp": 1698960084
}

Payload JWT ditandatangani menggunakan akun layanan yang ditentukan dalam klaim iss.

Membuat JWT

Pastikan Anda (pemanggil) dapat menggunakan peran roles/iam.serviceAccountTokenCreator di akun layanan.
Buat file JSON bernama jwt_in.json yang berisi JWT mentah:
```
SA="serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com"
cat << EOF > jwt_in.json
{
  "aud": "AUDIENCES",
  "sub": "AUDIENCES",
  "iss": "${SA}",
  "iat": $(date +%s),
  "exp": $(expr $(date +%s) + 600)
}
EOF
```
Ganti nilai berikut:
- SERVICE_ACCOUNT_ID: ID untuk akun layanan.
- PROJECT_ID: ID Google Cloud project Anda.
- AUDIENCES: String deskriptif yang mengidentifikasi audiens yang diharapkan untuk layanan, workload, atau aplikasi Anda, misalnya, "123456-my-app".

Menandatangani JWT (REST API)

Dengan menggunakan alat jq, buat payload permintaan curl dengan mengenkode JWT ke dalam string:
```
cat jwt_in.json | jq -Rsa >request.json
```

Tanda tangani token dengan meneruskan payload permintaan ke metode signJwt REST API.

SA="serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com"
curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" \
   -d @request.json \
   "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$SA:signJwt"

Ganti nilai berikut:

SERVICE_ACCOUNT_ID: ID untuk akun layanan.
PROJECT_ID: ID Google Cloud project Anda.

Simpan nilai signedJwt yang ditampilkan ke dalam variabel lingkungan yang disebut signedJwt.

Menandatangani JWT (gcloud CLI)

Atau, Anda dapat menandatangani JWT dengan meneruskan file jwt_in.json langsung ke gcloud CLI sign-jwt metode.

gcloud iam service-accounts sign-jwt jwt_in.json jwt_out \
   --iam-account=SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com

Ganti nilai berikut:

SERVICE_ACCOUNT_ID: ID untuk akun layanan.
PROJECT_ID: ID Google Cloud project Anda.

JWT yang ditandatangani ditampilkan dalam file output jwt_out. Simpan ke dalam variabel lingkungan yang disebut signedJwt.

Mengirim JWT yang ditandatangani ke endpoint indeks

Python

Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Python dokumentasi referensi API.

def vector_search_match_jwt(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    num_neighbors: int,
    signed_jwt: str,
) -> List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]]:
    """Query the vector search index.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against. The endpoint must be a private endpoint.
        deployed_index_id (str): Required. The ID of the DeployedIndex to run
        the queries against.
        queries (List[List[float]]): Required. A list of queries. Each query is
        a list of floats, representing a single embedding.
        num_neighbors (int): Required. The number of neighbors to return.
        signed_jwt (str): Required. The signed JWT token for the private
        endpoint. The endpoint must be configured to accept tokens from JWT's
        issuer and encoded audience.

    Returns:
        List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]] - A list of nearest neighbors for each query.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index endpoint instance from an existing endpoint.
    my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint(
        index_endpoint_name=index_endpoint_name
    )

    # Query the index endpoint for matches.
    resp = my_index_endpoint.match(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors,
        signed_jwt=signed_jwt,
    )
    return resp

Command-line

Dari VM Compute Engine di jaringan VPC yang sama, panggil endpoint MatchService gRPC, dengan meneruskan token signedJwt di header authorization, seperti yang ditunjukkan dalam contoh berikut:

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match \
   '{deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]}' \
   --metadata "authorization: Bearer $signedJwt"

Untuk menjalankan perintah ini, Anda harus menetapkan variabel lingkungan berikut:

TARGET_IP adalah alamat IP untuk server indeks yang di-deploy. Untuk mempelajari cara mengambil nilai ini, lihat Indeks kueri untuk mendapatkan tetangga terdekat.
DEPLOYED_INDEX_ID: String yang ditentukan pengguna untuk mengidentifikasi indeks yang di-deploy secara unik. Nama ini harus diawali dengan huruf dan hanya berisi huruf, angka, atau garis bawah. Lihat DeployedIndex.id untuk panduan format.

signedJwt adalah variabel lingkungan yang berisi JWT yang ditandatangani.

Pemecahan masalah

Tabel berikut mencantumkan beberapa pesan error gRPC umum.

Pesan Error gRPC	Alasan
Authorization header not found for index '`INDEX_ID`'	Metadata gRPC tidak berisi header otorisasi
JWT is invalid format	Token salah format dan tidak dapat diuraikan dengan benar
JWT authentication failed	Token telah habis masa berlakunya atau tidak ditandatangani oleh akun layanan yang benar
JWT issuer should be in the allowed issuers list	`iss` token tidak ada dalam penerbit yang diizinkan `auth_config`
Permission check fail for index '`INDEX_ID`'	Klaim `aud` atau `sub` token tidak ada dalam audiens `auth_config`

Langkah berikutnya

Untuk mempelajari lebih lanjut struktur klaim JWT dan token, lihat RFC 7519.
Pelajari lebih lanjut cara Membuat Token Web JSON (JWT) yang ditandatangani sendiri
Pelajari cara Mengupdate dan membuat kembali indeks
Pelajari cara Memantau indeks

Autentikasi Token Web JSON Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Batasan

Membuat dan menggunakan JWT untuk membuat kueri indeks

Membuat indeks

Membuat endpoint pribadi

Membuat akun layanan

Men-deploy indeks ke endpoint dengan konfigurasi autentikasi JWT

Membuat kueri indeks dengan JWT yang ditandatangani sendiri

Python

Membuat dan Menandatangani payload JWT

Command-line

Membuat payload JWT

Membuat JWT

Menandatangani JWT (REST API)

Menandatangani JWT (gcloud CLI)

Mengirim JWT yang ditandatangani ke endpoint indeks

Python

Command-line

Pemecahan masalah

Langkah berikutnya

Autentikasi Token Web JSON