Membuat permintaan HTTP

Anda dapat menentukan langkah alur kerja yang melakukan panggilan HTTP dan menetapkan respons dari panggilan ke variabel. Misalnya, Anda dapat memanggil layanan Google Cloud seperti Cloud Functions atau Cloud Run melalui permintaan HTTP.

Memanggil endpoint HTTP

Jenis langkah ini memungkinkan Anda membuat permintaan HTTP. Baik permintaan HTTP maupun HTTPS didukung. Metode permintaan HTTP yang paling umum memiliki pintasan panggilan (seperti http.get dan http.post), tetapi Anda dapat membuat jenis permintaan HTTP apa pun dengan menyetel kolom call ke http.request dan menentukan jenis permintaan menggunakan kolom method.

YAML

  - STEP_NAME:
      call: HTTP_REQUEST
      args:
          url: URL_VALUE
          method: REQUEST_METHOD
          private_service_name: "REGISTERED_SERVICE"
          headers:
              HEADER_KEY:HEADER_VALUE
              ...
          body:
              BODY_KEY:BODY_VALUE
              ...
          query:
              QUERY_KEY:QUERY_VALUE
              ...
          auth:
              type: AUTH_TYPE
              scope: AUTH_SCOPE
              scopes: AUTH_SCOPE
              audience: AUDIENCE
          timeout: TIMEOUT_IN_SECONDS
      result: RESULT_VALUE

JSON

  [
    {
      "STEP_NAME": {
        "call": "HTTP_REQUEST",
        "args": {
          "url": "URL_VALUE",
          "method": "REQUEST_METHOD",
          "private_service_name": "REGISTERED_SERVICE",
          "headers": {"HEADER_KEY":"HEADER_VALUE",
          ...
          },
          "body": {"BODY_KEY":"BODY_VALUE",
          ...
          },
          "query": {"QUERY_KEY":"QUERY_VALUE",
          ...
          },
          "auth": {
            "type":"AUTH_TYPE",
            "scope":"AUTH_SCOPE",
            "scopes":"AUTH_SCOPE",
            "audience":"AUDIENCE"
          },
          "timeout": "TIMEOUT_IN_SECONDS"
        },
        "result": "RESULT_VALUE"
      }
    }
  ]

Ganti kode berikut:

HTTP_REQUEST: wajib diisi. Gunakan salah satu opsi berikut untuk permintaan HTTP:
- http.delete
- http.get
- http.patch
- http.post
- http.put
- http.request
URL_VALUE: wajib diisi. URL tujuan pengiriman permintaan.
REQUEST_METHOD: diperlukan jika menggunakan jenis panggilan http.request. Jenis metode permintaan HTTP yang akan digunakan. Contoh:
- GET
- POST
- PATCH
- DELETE
REGISTERED_SERVICE: optional. Nama layanan Direktori Layanan yang terdaftar dalam format projects/PROJECT_ID/locations/LOCATION/namespaces/NAMESPACE_NAME/services/SERVICE_NAME. Untuk mengetahui informasi selengkapnya, lihat Memanggil endpoint pribadi yang sesuai dengan Kontrol Layanan VPC.
HEADER_KEY:HEADER_VALUE: opsional. Kolom header untuk memberikan input ke API.
Jika Anda menggunakan header Content-Type untuk menentukan jenis media dari isi permintaan, hanya jenis berikut yang didukung:
- application/json atau application/type+json—harus berupa peta
- application/x-www-form-urlencoded—harus berupa string yang tidak dienkode
- text/type—harus berupa string
Jika header Content-Type ditentukan, bagian isi akan dienkode seperti yang ditentukan. Misalnya, URL mungkin dienkode dengan JSON atau URL.

Jika Anda menggunakan header User-Agent untuk mengidentifikasi agen pengguna yang meminta, hal berikut akan berlaku:
- Defaultnya adalah GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs)
- Jika nilai ditentukan, GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs) akan ditambahkan ke nilai tersebut
  Contohnya, jika User-Agent: "MY_USER_AGENT_VALUE" ditentukan, header permintaan HTTP akan menjadi sebagai berikut (dengan spasi antara nilai yang ditentukan dan nilai default yang ditambahkan):
```
MY_USER_AGENT_VALUE GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs)
```

BODY_KEY:BODY_VALUE: opsional. Kolom isi untuk memberikan input ke API.

Jika header Content-Type tidak ditentukan, dan jika terdapat isi permintaan, hal berikut akan berlaku:

Jika nilai isi adalah byte, header akan disetel ke Content-Type: application/octet-stream.
Jika tidak, isi akan dienkode JSON dan header akan disetel ke Content-Type: application/json; charset=utf-8.

Contoh berikut adalah struktur bodi yang setara dengan payload JSON:

YAML

body:
  requests:
  - image:
      source:
        gcsImageUri: ${gsUri}
    features:
    - type: LABEL_DETECTION
    - type: SAFE_SEARCH_DETECTION
    - type: IMAGE_PROPERTIES
result: imageAnalysisResponse

JSON

{
  "requests":[
    {
      "image": {
        "source": {
            "gcsUri": "img.png"
        }
      },
      "features": [
        { "type":"LABEL_DETECTION" },
        { "type":"SAFE_SEARCH_DETECTION" },
        { "type":"IMAGE_PROPERTIES" },
      ]
    }
  ]
}

QUERY_KEY:QUERY_VALUE: opsional. Kolom kueri untuk memberikan input ke API.
AUTH_TYPE: optional. Diperlukan jika API yang dipanggil memerlukan autentikasi. Gunakan OIDC atau OAuth2. Untuk mengetahui informasi selengkapnya, lihat Membuat permintaan terautentikasi dari alur kerja.
- AUTH_SCOPE: optional. Membatasi akses aplikasi ke akun pengguna. Gunakan kunci scope atau scopes.
  Kunci scope mendukung string atau daftar string. Contoh:
  "https://www.googleapis.com/auth/cloud-platform"
  atau
  ["https://www.googleapis.com/auth/cloud-platform", "scope2", "scope3"]
  Kunci scopes, selain mendukung string atau daftar string, juga mendukung spasi dan string yang dipisahkan koma. Contoh:
  "https://www.googleapis.com/auth/cloud-platform scope2 scope3"
  atau
  "https://www.googleapis.com/auth/cloud-platform,scope2,scope3"
  Untuk informasi selengkapnya, lihat Cakupan OAuth 2.0 untuk Google API.
- AUDIENCE: optional. Menentukan audiens untuk token OIDC. Secara default, nilai ini ditetapkan ke nilai yang sama dengan url; tetapi, harus ditetapkan ke URL root layanan Anda. Contoh: https://region-project.cloudfunctions.net/hello_world.
TIMEOUT_IN_SECONDS: optional. Durasi permintaan diizinkan untuk berjalan dalam detik sebelum menampilkan pengecualian. Durasi maksimumnya adalah 1.800 detik.
RESULT_VALUE: optional. Nama variabel tempat hasil langkah pemanggilan HTTP disimpan.

Mengakses data respons HTTP yang disimpan dalam variabel

Jika header Content-Type untuk respons menentukan jenis media application/json, respons JSON yang disimpan dalam variabel akan otomatis dikonversi menjadi peta yang dapat diakses.

Jika perlu, ubah API yang dipanggil untuk menentukan jenis media application/json untuk header respons Content-Type. Jika tidak, Anda dapat menggunakan fungsi json.decode dan text.encode untuk mengonversi isi respons menjadi peta. Contoh:

json.decode(text.encode(RESPONSE_FROM_API))

Alur kerja menyertakan parser bawaan untuk mengakses data ini. Untuk mengakses kolom dari respons HTTP, gunakan sintaksis berikut:

${VARIABLE_NAME.body|code|headers.PATH_TO_FIELD}

Ganti kode berikut:

VARIABLE_NAME: nama variabel alur kerja tempat Anda menyimpan respons JSON.
body: gunakan kolom body untuk mengakses isi respons HTTP.
code: gunakan kolom code untuk mengakses kode respons HTTP.
headers: gunakan kolom headers untuk mengakses header respons HTTP berdasarkan nama.
PATH_TO_FIELD: jalur ke kolom dalam respons JSON yang ingin Anda akses. Mungkin hanya nama kolom, atau jika kolom disarangkan di dalam objek, kolom tersebut dapat berbentuk object1.object2.field.

Misalnya, jika API menampilkan {"age":50} dan alur kerja menyimpan respons tersebut dalam variabel bernama age_response, contoh berikut menampilkan nilai kolom age; dalam hal ini, 50:

age_response.body.age

Sampel

Contoh ini menunjukkan sintaksis.

Menetapkan respons dari panggilan API

Kecuali jika Anda memasukkan istilah penelusuran sendiri, contoh ini menggunakan lokasi Google Cloud Anda untuk membuat istilah penelusuran, yang akan diteruskan ke Wikipedia API. Daftar artikel Wikipedia terkait akan ditampilkan.

YAML

main:
  params: [input]
  steps:
    - checkSearchTermInInput:
        switch:
          - condition: '${"searchTerm" in input}'
            assign:
              - searchTerm: '${input.searchTerm}'
            next: readWikipedia
    - getLocation:
        call: sys.get_env
        args:
          name: GOOGLE_CLOUD_LOCATION
        result: location
    - setFromCallResult:
        assign:
          - searchTerm: '${text.split(location, "-")[0]}'
    - readWikipedia:
        call: http.get
        args:
          url: 'https://en.wikipedia.org/w/api.php'
          query:
            action: opensearch
            search: '${searchTerm}'
        result: wikiResult
    - returnOutput:
        return: '${wikiResult.body[1]}'

JSON

{
  "main": {
    "params": [
      "input"
    ],
    "steps": [
      {
        "checkSearchTermInInput": {
          "switch": [
            {
              "condition": "${\"searchTerm\" in input}",
              "assign": [
                {
                  "searchTerm": "${input.searchTerm}"
                }
              ],
              "next": "readWikipedia"
            }
          ]
        }
      },
      {
        "getLocation": {
          "call": "sys.get_env",
          "args": {
            "name": "GOOGLE_CLOUD_LOCATION"
          },
          "result": "location"
        }
      },
      {
        "setFromCallResult": {
          "assign": [
            {
              "searchTerm": "${text.split(location, \"-\")[0]}"
            }
          ]
        }
      },
      {
        "readWikipedia": {
          "call": "http.get",
          "args": {
            "url": "https://en.wikipedia.org/w/api.php",
            "query": {
              "action": "opensearch",
              "search": "${searchTerm}"
            }
          },
          "result": "wikiResult"
        }
      },
      {
        "returnOutput": {
          "return": "${wikiResult.body[1]}"
        }
      }
    ]
  }
}

Membuat permintaan POST HTTP eksternal

Contoh ini membuat permintaan POST ke endpoint HTTP eksternal.

YAML

- get_message:
    call: http.post
    args:
      url: https://www.example.com/endpoint
      body:
        some_val: "Hello World"
        another_val: 123
    result: the_message
- return_value:
    return: ${the_message.body}

JSON

[
  {
    "get_message": {
      "call": "http.post",
      "args": {
        "url": "https://www.example.com/endpoint",
        "body": {
          "some_val": "Hello World",
          "another_val": 123
        }
      },
      "result": "the_message"
    }
  },
  {
    "return_value": {
      "return": "${the_message.body}"
    }
  }
]

Membuat permintaan GET HTTP eksternal dengan header

Contoh ini membuat permintaan GET HTTP dengan header kustom. Anda juga dapat memberikan definisi header kustom saat membuat jenis permintaan HTTP lainnya.

YAML

- get_message:
    call: http.get
    args:
      url: https://www.example.com/endpoint
      headers:
        Content-Type: "text/plain"
      query:
        some_val: "Hello World"
        another_val: 123
    result: the_message
- return_value:
    return: ${the_message.body}

JSON

[
  {
    "get_message": {
      "call": "http.get",
      "args": {
        "url": "https://www.example.com/endpoint",
        "headers": {
          "Content-Type": "text/plain"
        },
        "query": {
          "some_val": "Hello World",
          "another_val": 123
        }
      },
      "result": "the_message"
    }
  },
  {
    "return_value": {
      "return": "${the_message.body}"
    }
  }
]

Menggunakan OIDC untuk melakukan autentikasi saat membuat permintaan ke Cloud Functions

Contoh ini membuat permintaan HTTP menggunakan OIDC dengan menambahkan bagian auth ke bagian args dalam definisi alur kerja, setelah menentukan URL-nya.

YAML

- call_my_function:
    call: http.post
    args:
      url: https://us-central1-myproject123.cloudfunctions.net/myfunc1
      auth:
        type: OIDC
      body:
        some_val: "Hello World"
        another_val: 123
    result: the_message
- return_value:
    return: ${the_message.body}

JSON

[
  {
    "call_my_function": {
      "call": "http.post",
      "args": {
        "url": "https://us-central1-myproject123.cloudfunctions.net/myfunc1",
        "auth": {
          "type": "OIDC"
        },
        "body": {
          "some_val": "Hello World",
          "another_val": 123
        }
      },
      "result": "the_message"
    }
  },
  {
    "return_value": {
      "return": "${the_message.body}"
    }
  }
]

Menangkap dan menangani error permintaan HTTP

Contoh ini menerapkan pengendali pengecualian kustom berdasarkan kode status HTTP yang ditampilkan oleh permintaan GET. Alur kerja menangkap potensi pengecualian dan menampilkan pesan error yang telah ditentukan. Jika pengecualian tidak dikenali, eksekusi alur kerja akan gagal dan menampilkan pengecualian seperti yang ditampilkan oleh permintaan GET. Untuk tag error lainnya, lihat Error alur kerja.

YAML

- read_item:
    try:
      call: http.get
      args:
        url: https://example.com/someapi
        auth:
          type: OIDC
      result: API_response
    except:
      as: e
      steps:
        - known_errors:
            switch:
              - condition: ${not("HttpError" in e.tags)}
                next: connection_problem
              - condition: ${e.code == 404}
                next: url_not_found
              - condition: ${e.code == 403}
                next: auth_problem
        - unhandled_exception:
            raise: ${e}
- url_found:
    return: ${API_response.body}
- connection_problem:
    return: "Connection problem; check URL"
- url_not_found:
    return: "Sorry, URL wasn't found"
- auth_problem:
    return: "Authentication error"

JSON

[
  {
    "read_item": {
      "try": {
        "call": "http.get",
        "args": {
          "url": "https://example.com/someapi",
          "auth": {
            "type": "OIDC"
          }
        },
        "result": "API_response"
      },
      "except": {
        "as": "e",
        "steps": [
          {
            "known_errors": {
              "switch": [
                {
                  "condition": "${not(\"HttpError\" in e.tags)}",
                  "next": "connection_problem"
                },
                {
                  "condition": "${e.code == 404}",
                  "next": "url_not_found"
                },
                {
                  "condition": "${e.code == 403}",
                  "next": "auth_problem"
                }
              ]
            }
          },
          {
            "unhandled_exception": {
              "raise": "${e}"
            }
          }
        ]
      }
    }
  },
  {
    "url_found": {
      "return": "${API_response.body}"
    }
  },
  {
    "connection_problem": {
      "return": "Connection problem; check URL"
    }
  },
  {
    "url_not_found": {
      "return": "Sorry, URL wasn't found"
    }
  },
  {
    "auth_problem": {
      "return": "Authentication error"
    }
  }
]

Membuat permintaan HTTP

Memanggil endpoint HTTP

YAML

JSON

YAML

JSON

Mengakses data respons HTTP yang disimpan dalam variabel

Sampel

Menetapkan respons dari panggilan API

YAML

JSON

Membuat permintaan POST HTTP eksternal

YAML

JSON

Membuat permintaan GET HTTP eksternal dengan header

YAML

JSON

Menggunakan OIDC untuk melakukan autentikasi saat membuat permintaan ke Cloud Functions

YAML

JSON

Menangkap dan menangani error permintaan HTTP

YAML

JSON

Langkah selanjutnya