Lihat konektor yang didukung untuk Integration Aplikasi.

Tugas Cloud Function

Tugas Cloud Function memungkinkan Anda mengonfigurasi dan menjalankan Google Cloud Functions dari integrasi. Google Cloud Functions adalah solusi komputasi ringan bagi developer untuk membuat fungsi mandiri dan bertujuan tunggal yang merespons peristiwa Cloud tanpa perlu mengelola server atau lingkungan runtime.

Untuk informasi selengkapnya, lihat dokumentasi Google Cloud Functions.

Sebelum memulai

Pastikan Anda melakukan tugas berikut di project Google Cloud sebelum mengonfigurasi tugas Cloud Function.

  1. Aktifkan Cloud Functions API (cloudfunctions.googleapis.com).

    Mengaktifkan Cloud Functions API

  2. Tetapkan peran IAM berikut kepada akun utama Anda:
    • Cloud Functions Admin (roles/cloudfunctions.admin)
    • Editor Integrasi Aplikasi (roles/integrations.integrationEditor)
    • (roles/iam.serviceAccountUser) Pengguna Akun Layanan

    Untuk mengetahui informasi tentang cara memberikan peran kepada akun utama, lihat Memberikan, mengubah, dan mencabut akses.

  3. Untuk terhubung ke fungsi Cloud Run, pastikan Anda telah membuat profil OAuth 2.0 atau melampirkan akun layanan yang dikelola pengguna ke integrasi Anda:
    • Jika integrasi Anda memiliki akun layanan yang terpasang, tetapkan peran IAM Cloud Function Invoker ke akun layanan tersebut.

      Untuk informasi tentang cara memberikan peran ke akun layanan, lihat Mengelola akses ke akun layanan.

    • Tugas Cloud Function hanya mendukung profil autentikasi jenis Token ID OIDC Google. Buat profil autentikasi jenis Token ID OIDC Google menggunakan akun layanan dengan peran IAM Cloud Function Invoker yang ditetapkan. Jika tugas Cloud Function Anda tidak memerlukan autentikasi, kolom Authentication profile di panel konfigurasi tugas dapat dibiarkan kosong.

    Jika integrasi Anda memiliki profil ID OIDC dan akun layanan yang dikelola pengguna yang dikonfigurasi, secara default profil ID OIDC akan digunakan untuk autentikasi. Jika profil ID OIDC atau akun layanan yang dikelola pengguna tidak dikonfigurasi, akun layanan default (service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com) akan digunakan untuk memanggil tugas Cloud Function.

  4. Pastikan Kontrol Layanan VPC TIDAK disiapkan untuk Integrasi Aplikasi di project Google Cloud Anda.

Mengonfigurasi tugas Cloud Function

Untuk mengonfigurasi tugas Cloud Function dalam integrasi Anda, lakukan langkah-langkah berikut:

  1. Di konsol Google Cloud, buka halaman Integrasi Aplikasi.

    Buka Application Integration

  2. Di menu navigasi, klik Integrations.

    Halaman Integrasi akan muncul yang mencantumkan semua integrasi yang tersedia di project Google Cloud.

  3. Pilih integrasi yang ada atau klik Buat integrasi untuk membuat integrasi baru.

    Jika Anda membuat integrasi baru:

    1. Masukkan nama dan deskripsi di panel Buat Integrasi.
    2. Pilih region untuk integrasi.
    3. Pilih akun layanan untuk integrasi. Anda dapat mengubah atau memperbarui detail akun layanan integrasi kapan saja dari panel Ringkasan integrasi di toolbar integrasi.
    4. Klik Create.

    Tindakan ini akan membuka integrasi di editor integrasi.

  4. Di menu navigasi editor integrasi, klik Tugas untuk melihat daftar tugas dan konektor yang tersedia.
  5. Klik dan tempatkan elemen Cloud Function ke editor integrasi.
  6. Klik elemen Cloud Function di desainer untuk membuka panel konfigurasi, lalu klik Configure Cloud Function.
  7. Dalam dialog Cloud Function Configuration, pilih salah satu dari opsi berikut:
    • Tautkan fungsi yang ada. Pilih opsi ini untuk menautkan Cloud Function yang ada yang dikonfigurasi dalam integrasi. Masukkan URL Pemicu Cloud Function.
    • Buat fungsi baru. Pilih opsi ini untuk membuat Cloud Function baru yang terkait dengan integrasi. Masukkan Cloud Function Name dan pilih function region dari menu drop-down.
  8. Klik Simpan.

    Fungsi Google Cloud dasar–dibuat dengan template Python- dibuat di project Google Cloud Anda dan dikaitkan dengan integrasi Anda. Panel konfigurasi tugas menampilkan URL Pemicu dan Parameter Tugas Cloud Function.

Template Cloud Function

Contoh berikut menunjukkan cara menggunakan tugas Cloud Function dalam integrasi Anda untuk berbagai bahasa.

Python

Saat mengonfigurasi Cloud Function menggunakan Cloud Function yang ada, pastikan file sumber main.py, task.py, dan requirements.txt fungsi tersebut dalam format berikut:

task.py

      # Sample Code:
      # print(event.get('task_string_key'))
      # event.set('task_int_array_key', [456, 789]);
      # event.log('some logging')
      
      def run(event):
        """Actual cloud function custom logic.
        Args:
          event : event object in main.py that contains all parameters.
        """
        return

main.py

      """Un-editable platform wrapper which invokes user code."""
    import traceback
    
    from flask import json
    from flask import jsonify
    from task import run
    
    VALUE_NAME = [
        'stringValue', 'intValue', 'doubleValue', 'booleanValue', 'protoValue'
    ]
    ARRAY_VALUE_NAME = {
        'stringArray': 'stringValues',
        'intArray': 'intValues',
        'doubleArray': 'doubleValues',
        'booleanArray': 'booleanValues',
        'protoArray': 'protoValues'
    }
    VALUE_TYPE_URL = 'type.googleapis.com/google.protobuf.Value'
    CLOUD_FUNCTION_EXCEPTION_KEY = 'CloudFunctionException'
    CLOUD_FUNCTION_LOGGING_KEY = 'CloudFunctionLogging'
    
    
    class _Event(object):
      """Event object."""
    
      def __init__(self, json_payload):
        self._event_params = json_payload.get('eventParameters', dict())
        self._task_params = json_payload.get('taskParameters', dict())
        self._log = []
        print('Event param is ' + str(self._event_params))
        print('Task param is ' + str(self._task_params))
    
      def set(self, key, value):
        """Set the event parameters key-value.
    
        Args:
          key: parameter key.
          value: parameter value.
        """
        new_param = self._create_param(key, value)
        param = self._get_param_by_key(key)
        if param is None:
          if 'parameters' not in self._event_params:
            self._event_params['parameters'] = []
          self._event_params['parameters'].append(new_param)
        else:
          param['value'] = new_param['value']
    
      def _create_param(self, key, value):
        """Create a new parameter with given key value pair.
    
        Args:
          key: parameter key.
          value: parameter value.
    
        Returns:
          parameter.
        """
        new_param = {}
        new_param['key'] = key
        if isinstance(value, str):
          new_param['value'] = {'stringValue': value}
        elif isinstance(value, int):
          new_param['value'] = {'intValue': value}
        elif isinstance(value, float):
          new_param['value'] = {'doubleValue': value}
        elif isinstance(value, bool):
          new_param['value'] = {'booleanValue': value}
        elif isinstance(value, dict):
          if 'type@' in value:
            new_param['value'] = {'protoValue': value}
          else:
            new_param['value'] = {
                'protoValue': {
                    '@type': 'type.googleapis.com/google.protobuf.Value',
                    'value': value
                }
            }
        elif isinstance(value, list):
          if not value:
            raise RuntimeError('Cannot create a param with empty list')
          if any(not isinstance(val, type(value[0])) for val in value):
            print('Not all elements in the list have the same type')
            new_param['value'] = {
                'protoValue': {
                    '@type': 'type.googleapis.com/google.protobuf.Value',
                    'value': value
                }
            }
          elif isinstance(value[0], str):
            new_param['value'] = {'stringArray': {'stringValues': value}}
          elif isinstance(value[0], int):
            new_param['value'] = {'intArray': {'intValues': value}}
          elif isinstance(value[0], float):
            new_param['value'] = {'doubleArray': {'doubleValues': value}}
          elif isinstance(value[0], bool):
            new_param['value'] = {'booleanArray': {'booleanValues': value}}
          elif isinstance(value[0], dict):
            if all('@type' in val and val['@type'] == value[0]['@type']
                   for val in value):
              new_param['value'] = {'protoArray': {'protoValues': value}}
            else:
              new_param['value'] = {
                  'protoValue': {
                      '@type': 'type.googleapis.com/google.protobuf.Value',
                      'value': value
                  }
              }
          else:
            raise RuntimeError('The type ' + type(value[0]) +
                               ' in the list is not supported')
        else:
          raise RuntimeError('Value ' + str(value) + ' has the type ' +
                             type(value) + ' that is not supported')
        return new_param
    
      def get(self, key):
        """Get the event parameter value for specified key.
    
        Args:
          key: parameter key.
    
        Returns:
          Parameter value.
        """
        param = self._get_param_by_key(key)
        if param is None:
          raise RuntimeError('Can not find param with key ' + key)
        return self._get_param_value(param)
    
      def _get_param_by_key(self, key):
        """Get the parameter for specified key.
    
        Args:
          key: parameter key.
    
        Returns:
          Parameter.
        """
        param = self._get_param_by_key_from_params(key, self._task_params)
        if param is None:
          return self._get_param_by_key_from_params(key, self._event_params)
        value = self._get_param_value(param)
        if isinstance(value, str) and len(value) > 2 and value.startswith(
            '$') and value.endswith('$'):
          return self._get_param_by_key_from_params(value[1:-1], self._event_params)
        return param
    
      def _get_param_by_key_from_params(self, key, params):
        """Get the parameter for specified key from event parameters.
    
        Args:
          key: parameter key.
          params: event parameters.
    
        Returns:
          Parameter.
        """
        if not isinstance(params, dict) or 'parameters' not in params:
          return None
        for param in params['parameters']:
          if param['key'] == key:
            return param
        return None
    
      def _get_param_value(self, param):
        """Get the parameter value for specified parameter.
    
        Args:
          param: parameter.
    
        Returns:
          Parameter value.
        """
        value = param['value']
        if len(value) != 1:
          raise RuntimeError('param does not have size of 1')
        for value_name in VALUE_NAME:
          if value_name in value:
            if value_name == 'protoValue' and value[value_name][
                '@type'] == VALUE_TYPE_URL:
              return value[value_name]['value']
            return value[value_name]
        for array_value_name in ARRAY_VALUE_NAME:
          if array_value_name in value:
            return value[array_value_name][ARRAY_VALUE_NAME[array_value_name]]
        raise RuntimeError('Cannot get value from param ' + str(param))
    
      def set_error(self):
        """Set the cloud function error to event parameters in order for user to see on IP."""
    
        self.set(CLOUD_FUNCTION_EXCEPTION_KEY, traceback.format_exc())
    
      def log(self, message):
        self._log.append(str(message))
    
      def get_response(self):
        """Get the response that can be returned to IP.
    
        Returns:
          The response text or any set of values that can be turned into a
          Response object using
          `make_response
          <http://flask.pocoo.org/docs/1.0/api/#flask.Flask.make_response>`.
        """
        if self._log:
          self.set(CLOUD_FUNCTION_LOGGING_KEY, self._log)
        res = {
            'eventParameters': self._event_params,
        }
        return jsonify(**json.loads(json.htmlsafe_dumps(res)))
    
    
    def execute_function(request):
      """Entry point of the cloud function.
    
      Args:
        request (flask.Request): HTTP request object.
    
      Returns:
        The response text or any set of values that can be turned into a
        Response object using
        `make_response
        <http://flask.pocoo.org/docs/1.0/api/#flask.Flask.make_response>`.
      """
      try:
        request_json = request.get_json(silent=True)
        event = _Event(request_json)
        run(event)
      except:
        event.set_error()
      return event.get_response()

requirements.txt

    # Function dependencies, for example:
    # package>=version

Untuk mengetahui informasi selengkapnya tentang format respons, lihat ValueType.

Java

Contoh berikut menunjukkan cara menggunakan tugas Cloud Function dalam integrasi Anda. Pastikan respons mengikuti format JSON yang didukung seperti yang dijelaskan dalam contoh:

private static final Gson gson = new Gson();

@Override
public void service(HttpRequest request, HttpResponse response) throws Exception {
  JsonObject body = gson.fromJson(request.getReader(), JsonObject.class);

  JsonArray resParams = new JsonArray();
  for (JsonElement param: body.getAsJsonObject("eventParameters").getAsJsonArray("parameters")) {
    if (param.getAsJsonObject().get("key").getAsString().equals("input")) {
      JsonObject newParam= new JsonObject();
      newParam.addProperty("key", "input");
      JsonObject value = new JsonObject();
      value.addProperty("stringValue","2");
      newParam.add("value", value);
      resParams.add(newParam);
    } else {
      resParams.add(param);
    }
  }
  JsonObject parameters = new JsonObject();
  parameters.add("parameters", resParams);
  JsonObject res = new JsonObject();
  res.add("eventParameters", parameters);
  System.out.println(res);
  BufferedWriter writer = response.getWriter();
  writer.write(res.toString());
}

Untuk mengetahui informasi selengkapnya tentang format respons, lihat ValueType.

JavaScript

Contoh berikut menunjukkan cara menggunakan tugas Cloud Function dalam integrasi Anda. Pastikan respons mengikuti format JSON yang didukung seperti yang dijelaskan dalam contoh:

const functions = require('@google-cloud/functions-framework');

functions.http('execute_function', (req, res) => {
  console.log(JSON.stringify(req.body));
  let response = {"eventParameters":{"parameters":[{"key":"input","value":{"stringValue":"2"}}]}};
  res.send(JSON.stringify(response));
});

Untuk mengetahui informasi selengkapnya tentang format respons, lihat ValueType.

PHP

Contoh berikut menunjukkan cara menggunakan tugas Cloud Function dalam integrasi Anda. Pastikan respons mengikuti format JSON yang didukung seperti yang dijelaskan dalam contoh:

use Psr\Http\Message\ServerRequestInterface;
function execute_function(ServerRequestInterface $request)
{
  return '{"eventParameters":{"parameters":[{"key":"input","value":{"stringValue":"2"}}]}}';
}

Untuk mengetahui informasi selengkapnya tentang format respons, lihat ValueType.

Mengedit tugas Cloud Function

Mengonfigurasi tugas Cloud Function di Integrasi Aplikasi akan membuat Cloud Function dasar yang dipicu HTTP di project Google Cloud Anda.

Untuk mengedit tugas Cloud Function, lakukan langkah-langkah berikut:

  1. Di panel konfigurasi tugas, klik Buka Cloud Function.

    Anda akan dialihkan ke halaman Detail fungsi di Konsol Google Cloud.

  2. Klik Edit.
  3. Halaman Configuration memungkinkan Anda mengedit setelan konfigurasi default Cloud Function. Lihat Mengonfigurasi Cloud Functions untuk mengetahui informasi selengkapnya.
  4. Klik Berikutnya untuk mengedit file kode sumber Cloud Function.

    Secara default, Cloud Function berisi file sumber berikut:

    • main.py : File ini berisi kode inisialisasi untuk menjalankan Cloud Function dari integrasi Anda.
    • task.py : File ini berisi kode Cloud Function yang dapat dieksekusi. Tulis skrip Anda di dalam fungsi run(event). Fungsi ini dipanggil saat tugas Cloud Function dijalankan. Objek event dari file main.py berisi semua parameter tugas.

      Lihat Mengakses variabel integrasi untuk mengetahui informasi tentang cara menggunakan variabel yang ditentukan di tingkat integrasi dalam skrip Anda.

  5. Klik Deploy.

Mengakses variabel integrasi

Untuk mengakses variabel integrasi di Cloud Function, Anda harus meneruskan variabel dalam bentuk parameter tugas ke tugas Cloud Function. Parameter tugas adalah key-value pair dengan Key adalah nama variabel referensi yang digunakan dalam file sumber Cloud Function Anda dan Value adalah nama variabel integrasi yang sesuai yang ditunjuk oleh variabel referensi. Anda dapat menambahkan satu atau beberapa parameter tugas di bagian Parameter Tugas pada panel konfigurasi tugas.

Metode berikut digunakan untuk mengakses variabel integrasi dari Cloud Function Anda:

  • set: Menulis nilai ke variabel.
  • get: Membaca nilai variabel.

Misalnya, jika Anda memiliki variabel integrasi bernama EmployeeName yang ingin digunakan dalam file sumber Cloud Functions, tentukan parameter tugas berikut:

  • Kunci: EmployeeKey
  • Nilai: EmployeeName

Contoh skrip berikut menunjukkan penggunaan fungsi set dan get untuk mengakses variabel integrasi yang ditentukan. 

def run(event):
  # Read the integration variable EmployeeName using the reference variable EmployeeKey
  value = event.get('EmployeeKey');
  # Change the integration variable EmployeeName value using the reference variable EmployeeKey
  newValue = event.set('EmployeeKey' , 'XYZ');
  # The new value of the integration variable is retained throughout the Cloud Function task.
  return

Strategi penanganan error

Strategi penanganan error untuk tugas menentukan tindakan yang akan diambil jika tugas gagal karena error sementara. Untuk mengetahui informasi tentang cara menggunakan strategi penanganan error, dan mengetahui berbagai jenis strategi penanganan error, lihat Strategi penanganan error.

Pengecualian SLA

Tugas Cloud Function memiliki dependensi pada produk Google Cloud Functions. Karena dependensi ini bersifat eksternal terhadap Integrasi Aplikasi, semua eksekusi integrasi active yang gagal karena kegagalan dalam tugas Cloud Function akan dikecualikan dari persyaratan dan ketentuan Perjanjian Tingkat Layanan (SLA) Integrasi Aplikasi.

Kuota dan batas

Untuk mengetahui informasi tentang kuota dan batas, lihat Kuota dan batas.

Langkah selanjutnya