Halaman ini diterjemahkan oleh Cloud Translation API.

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 dikeluarkan oleh akun layanan Google yang diotorisasi 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 API RPC bidang data (seperti MatchService) yang dipanggil menggunakan gRPC. Contoh RPC di halaman ini menggunakan alat grpc_cli open source untuk mengirim permintaan gRPC ke server indeks yang di-deploy.
API Admin untuk pembuatan, deployment, dan pengelolaan indeks diamankan dengan 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 Vector Search 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 untuk akun layanan tersebut.

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 cara 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." \
   --role "roles/iam.serviceAccountTokenCreator" \
   --member "serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID." \
   --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." \
   --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 pada 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." \
   --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: Google Cloud Project ID Anda.
- LOCATION: Region tempat Anda menggunakan Vertex AI.

Membuat kueri indeks dengan JWT yang ditandatangani sendiri

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

Buat payload JWT.
Tandatangani 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 dari library Kredensial IAM API Python untuk mendapatkan token bertanda tangan. 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.",
            "AUDIENCES")

Command-line

Buat payload JWT

Autentikasi Vector Search menerima JWT yang ditandatangani dengan akun layanan yang telah diberi otorisasi sebelumnya, untuk audiens yang telah ditentukan sebelumnya. 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 untuk audiens yang diberikan. 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."
```
Klaim aud (audiens) dan sub (subjek) harus ditetapkan ke nilai yang sama. Ini adalah string deskriptif yang mengidentifikasi audiens yang diharapkan untuk layanan, beban kerja, 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 saat token diterbitkan. Klaim exp (waktu habis masa berlaku) harus ditetapkan ke waktu yang tidak lama lagi (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 payload JWT tunggal:

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

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

Buat 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."
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: Google Cloud Project ID 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
```

Tandatangani token dengan meneruskan payload permintaan ke metode REST API signJwt.

SA="serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID."
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: Google Cloud Project ID 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 secara langsung ke metode gcloud CLI sign-jwt.

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

Ganti nilai berikut:

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

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

Kirim 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 Dokumentasi referensi API Python.

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 bertanda tangan Anda.

Pemecahan masalah

Tabel berikut mencantumkan beberapa pesan error gRPC yang umum.

Pesan Error gRPC	Alasan
Header otorisasi tidak ditemukan untuk indeks '`INDEX_ID`'	Metadata gRPC tidak berisi header otorisasi
JWT memiliki format yang tidak valid	Token memiliki format yang salah dan tidak dapat diurai dengan benar
Autentikasi JWT gagal	Token telah habis masa berlakunya atau tidak ditandatangani oleh akun layanan yang benar
Penerbit JWT harus ada dalam daftar penerbit yang diizinkan	Token `iss` tidak ada di penerbit yang diizinkan `auth_config`
Pemeriksaan izin gagal untuk indeks '`INDEX_ID`'	Klaim token `aud` atau `sub` tidak ada di audiens `auth_config`

Langkah berikutnya

Untuk mempelajari lebih lanjut JWT dan struktur klaim 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

Buat payload JWT

Buat JWT

Menandatangani JWT (REST API)

Menandatangani JWT (gcloud CLI)

Kirim JWT yang ditandatangani ke endpoint indeks

Python

Command-line

Pemecahan masalah

Langkah berikutnya

Autentikasi Token Web JSON