Menggunakan library klien Python

Tutorial ini menjelaskan cara menggunakan Library Klien Google API untuk Python guna memanggil AI Platform Training REST API di aplikasi Python Anda. Cuplikan kode dan contoh di bagian lain dokumentasi ini menggunakan library klien Python ini.

Anda akan membuat model di project Google Cloud dalam tutorial ini. Ini adalah tugas sederhana yang mudah dimuat ke dalam contoh kecil.

Tujuan

Ini adalah tutorial dasar yang dirancang untuk mengenalkan library klien Python ini kepada Anda. Setelah selesai, Anda akan dapat:

  • Dapatkan representasi Python dari layanan AI Platform Training.
  • Gunakan representasi tersebut untuk membuat model dalam project Anda, yang akan membantu Anda memahami cara memanggil API pengelolaan tugas dan model lainnya.

Biaya

Anda tidak akan ditagih untuk operasi dalam tutorial ini. Lihat halaman harga untuk mengetahui informasi selengkapnya.

Sebelum memulai

Menyiapkan project GCP

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the AI Platform Training & Prediction and Compute Engine APIs.

    Enable the APIs

  5. Install the Google Cloud CLI.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  8. Make sure that billing is enabled for your Google Cloud project.

  9. Enable the AI Platform Training & Prediction and Compute Engine APIs.

    Enable the APIs

  10. Install the Google Cloud CLI.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

Menyiapkan autentikasi

Untuk menyiapkan autentikasi, Anda perlu membuat kunci akun layanan dan menetapkan variabel lingkungan untuk jalur file ke kunci akun layanan.

  1. Buat akun layanan:

    1. Di konsol Google Cloud, buka halaman Buat akun layanan.

      Buka Buat akun layanan

    2. Di kolom Nama akun layanan, masukkan nama.
    3. Opsional: Di kolom Deskripsi akun layanan, masukkan deskripsi.
    4. Klik Buat.
    5. Klik kolom Pilih peran. Di bagian Semua peran, pilih AI Platform > AI Platform Admin.
    6. Klik Add another role.

    7. Klik kolom Pilih peran. Di bagian Semua peran, pilih Storage > Storage Object Admin.

    8. Klik Selesai untuk membuat akun layanan.

      Jangan tutup jendela browser Anda. Anda akan menggunakannya pada langkah berikutnya.

  2. Membuat kunci akun layanan untuk autentikasi:

    1. Di konsol Google Cloud, klik alamat email untuk akun layanan yang telah dibuat.
    2. Klik Kunci.
    3. Klik Tambahkan kunci, lalu Buat kunci baru.
    4. Klik Buat. File kunci JSON akan didownload ke komputer Anda.
    5. Klik Close.

  3. Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur file JSON yang berisi kunci akun layanan Anda. Variabel ini hanya berlaku untuk sesi shell Anda saat ini. Jadi, jika Anda membuka sesi baru, tetapkan variabel kembali.

Menyiapkan lingkungan pengembangan Python

Pilih salah satu opsi di bawah untuk menyiapkan lingkungan secara lokal di macOS atau di lingkungan jarak jauh di Cloud Shell.

Untuk pengguna macOS, sebaiknya siapkan lingkungan Anda menggunakan tab MACOS di bawah. Cloud Shell, yang ditampilkan di tab CLOUD SHELL, tersedia di macOS, Linux, dan Windows. Cloud Shell menyediakan cara cepat untuk mencoba Pelatihan AI Platform, tetapi tidak cocok untuk pekerjaan pengembangan yang sedang berlangsung.

macOS

  1. Periksa penginstalan Python
    Pastikan Anda telah menginstal Python dan, jika perlu, instal.

    python -V

  2. Periksa penginstalan pip
    pip adalah pengelola paket Python, yang disertakan dengan versi Python saat ini. Periksa apakah Anda telah menginstal pip dengan menjalankan pip --version. Jika belum, lihat cara menginstal pip.

    Anda dapat mengupgrade pip menggunakan perintah berikut:

    pip install -U pip

    Lihat dokumentasi pip untuk mengetahui detail selengkapnya.

  3. Instal virtualenv
    virtualenv adalah alat untuk membuat lingkungan Python yang terisolasi. Periksa apakah Anda telah menginstal virtualenv dengan menjalankan virtualenv --version. Jika tidak, instal virtualenv: 

    pip install --user --upgrade virtualenv

    Untuk membuat lingkungan pengembangan terisolasi bagi panduan ini, buat lingkungan virtual baru di virtualenv. Misalnya, perintah berikut mengaktifkan lingkungan bernama aip-env:

    virtualenv aip-env
source aip-env/bin/activate

  4. Untuk tujuan tutorial ini, jalankan perintah lainnya dalam lingkungan virtual Anda.

    Lihat informasi selengkapnya tentang penggunaan virtualenv. Untuk keluar dari virtualenv, jalankan deactivate.

Cloud Shell

  1. Buka konsol Google Cloud.

    Konsol Google Cloud

  2. Klik tombol Activate Google Cloud Shell di bagian atas jendela konsol.

    Mengaktifkan Google Cloud Shell

    Sesi Cloud Shell akan terbuka di dalam frame baru di bagian bawah konsol dan menampilkan perintah command line. Perlu waktu beberapa detik hingga sesi shell diinisialisasi.

    Sesi Cloud Shell

    Sesi Cloud Shell Anda siap digunakan.

  3. Konfigurasikan alat command line gcloud untuk menggunakan project yang Anda pilih. 

    gcloud config set project [selected-project-id]

    dengan [selected-project-id] sebagai project ID Anda. (Hapus tanda kurung yang mengapit.)

Menginstal Library Klien Google API untuk Python

Instal Library Klien Google API untuk Python.

Ini adalah tutorial dasar yang dirancang untuk mengenalkan library klien Python ini kepada Anda. Setelah selesai, Anda akan dapat:

  • Dapatkan representasi Python dari layanan AI Platform Training.
  • Gunakan representasi tersebut untuk membuat model dalam project Anda, yang akan membantu Anda memahami cara memanggil API pengelolaan tugas dan model lainnya.
Anda tidak akan ditagih untuk operasi dalam tutorial ini. Lihat halaman harga untuk mengetahui informasi selengkapnya.

Mengimpor modul yang diperlukan

Jika ingin menggunakan Library Klien Google API untuk Python guna memanggil AI Platform Training REST API dalam kode, Anda harus mengimpor paketnya dan paket OAuth2. Untuk tutorial ini (dan untuk sebagian besar penggunaan standar AI Platform Training), Anda hanya perlu mengimpor modul tertentu:

Lihat dokumentasi untuk paket tersebut guna mempelajari modul lain yang tersedia.

Buat file Python baru menggunakan editor favorit Anda, lalu tambahkan baris berikut:

from oauth2client.client import GoogleCredentials
from googleapiclient import discovery
from googleapiclient import errors

Membuat representasi Python dari API

Dapatkan representasi Python REST API Anda. Metode yang Anda panggil adalah build karena library klien API menggunakan penemuan layanan untuk menyiapkan koneksi secara dinamis ke layanan saat layanan tersebut ada saat Anda melakukan panggilan. Panggil objek yang mengenkapsulasi layanan ml:

ml = discovery.build('ml','v1')

Mengonfigurasi parameter dan isi permintaan

Untuk melakukan panggilan ke layanan, Anda harus membuat parameter dan isi permintaan yang akan diteruskan ke REST API. Anda meneruskan parameter sebagai parameter Python reguler ke metode yang mewakili panggilan. Isinya adalah resource JSON seperti yang akan Anda gunakan jika memanggil API dengan permintaan HTTP secara langsung.

Lihat REST API untuk membuat model di tab browser baru, projects.models.create:

  • Perhatikan parameter jalur parent, yang merupakan bagian dari URI permintaan yang mengidentifikasi project. Jika membuat permintaan HTTP POST secara langsung, Anda akan menggunakan URI berikut:

    https://ml.googleapis.com/v1/projects/YOUR_PROJECT_ID/models

    Saat menggunakan library klien API, bagian variabel URI direpresentasikan sebagai parameter berjenis string ke panggilan API. Anda akan menetapkannya ke 'projects/<var>YOUR_PROJECT_ID</var>'. Simpan project Anda dalam variabel untuk membuat panggilan API lebih rapi:

    project_id = 'projects/{}'.format('YOUR_PROJECT_ID')

  • Isi permintaan adalah resource JSON yang mewakili informasi model. Anda dapat melihat di definisi resource model bahwa definisi tersebut memiliki dua nilai untuk input: name dan (opsional) description. Anda dapat meneruskan kamus Python sebagai pengganti JSON dan library klien API akan melakukan konversi yang diperlukan.

    Buat kamus Python Anda:

    request_dict = {'name': 'your-model-name',
               'description': 'This is a machine learning model entry.'}

Membuat permintaan

Melakukan panggilan ke API dengan library klien Python memiliki dua langkah: pertama, Anda membuat permintaan, lalu melakukan panggilan menggunakan permintaan tersebut.

Membuat permintaan

Gunakan objek klien bawaan yang Anda buat sebelumnya (jika Anda mengikuti cuplikan kode dengan tepat, objek tersebut disebut ml) sebagai root hierarki API dan tentukan API yang ingin Anda gunakan. Setiap koleksi di jalur API berperilaku seperti fungsi yang menampilkan daftar koleksi dan metode di dalamnya. Misalnya, root dari semua AI Platform Training API adalah projects, sehingga panggilan Anda dimulai dengan ml.projects().

Gunakan kode ini untuk membuat permintaan Anda:

request = ml.projects().models().create(parent=project_id, body=request_dict)

Kirim permintaan

Permintaan yang Anda buat pada langkah terakhir mengekspos metode execute yang Anda panggil untuk mengirim permintaan ke layanan:

response = request.execute()

Developer biasanya menggabungkan langkah ini dengan langkah terakhir:

response = ml.projects().models().create(parent=project_id,
                                         body=request_dict).execute()

Menangani error sederhana

Banyak hal yang dapat terjadi saat Anda melakukan panggilan API melalui Internet. Sebaiknya tangani error umum. Cara termudah untuk menangani error adalah dengan menempatkan permintaan Anda dalam blok try dan menangkap kemungkinan error. Sebagian besar error yang mungkin Anda dapatkan dari layanan adalah error HTTP, yang dienkapsulasi dalam class HttpError. Untuk menangkap error ini, Anda akan menggunakan modul errors dari paket googleapiclient.

Gabungkan panggilan request.execute() dalam blok try. Masukkan juga pernyataan print dalam blok, sehingga Anda akan mencoba mencetak respons hanya jika panggilan berhasil:

try:
    response = request.execute()
    print(response)

Tambahkan blok catch untuk menangani error HTTP. Anda dapat menggunakan HttpError._get_reason() untuk mendapatkan kolom teks alasan dari respons:

except errors.HttpError, err:
    # Something went wrong, print out some information.
    print('There was an error creating the model. Check the details:')
    print(err._get_reason())

Tentu saja, pernyataan cetak sederhana mungkin bukan pendekatan yang tepat untuk aplikasi Anda.

Menggabungkan semuanya

Berikut adalah contoh lengkapnya:

from googleapiclient import discovery
from googleapiclient import errors

# Store your full project ID in a variable in the format the API needs.
project_id = 'projects/{}'.format('YOUR_PROJECT_ID')

# Build a representation of the Cloud ML API.
ml = discovery.build('ml', 'v1')

# Create a dictionary with the fields from the request body.
request_dict = {'name': 'your_model_name',
               'description': 'your_model_description'}

# Create a request to call projects.models.create.
request = ml.projects().models().create(
              parent=project_id, body=request_dict)

# Make the call.
try:
    response = request.execute()
    print(response)
except errors.HttpError, err:
    # Something went wrong, print out some information.
    print('There was an error creating the model. Check the details:')
    print(err._get_reason())

Mengeneralisasi ke metode lain

Anda dapat menggunakan prosedur yang telah Anda pelajari di sini untuk melakukan panggilan REST API lainnya. Beberapa API memerlukan resource JSON yang jauh lebih rumit daripada membuat model, tetapi prinsipnya sama:

  1. Impor googleapiclient.discovery dan googleapiclient.errors.

  2. Gunakan modul penemuan untuk membuat representasi Python dari API.

  3. Gunakan representasi API sebagai serangkaian objek bertingkat untuk membuka API yang Anda inginkan dan membuat permintaan. Misalnya,

    request = ml.projects().models().versions().delete(
    name='projects/myproject/models/mymodel/versions/myversion')

  4. Panggil request.execute() untuk mengirim permintaan, yang menangani pengecualian dengan cara yang sesuai untuk aplikasi Anda.

  5. Jika ada isi respons, Anda dapat memperlakukannya seperti kamus Python untuk mendapatkan objek JSON yang ditentukan dalam referensi API. Perhatikan bahwa banyak objek dalam respons memiliki kolom yang hanya ada dalam beberapa situasi. Anda harus selalu memeriksa untuk menghindari error kunci:

    response = request.execute()

some_value = response.get('some_key') or 'default_value'

Langkah selanjutnya