HTTP-Anfrage stellen

Sie können einen Workflowschritt definieren, der einen HTTP-Aufruf durchführt, und die Antwort des Aufrufs einer Variablen zuweisen. Beispielsweise können Sie über eine HTTP-Anfrage einen Google Cloud-Dienst wie Cloud Functions oder Cloud Run aufrufen.

Hinweis: Ein Google Cloud-Dienst über eine HTTP-Anfrage sollte nicht kann mit der Verwendung von Workflow-Connectors verwechselt werden um API-Vorgänge auszuführen, die Ihren Workflow in andere Google Cloud-Produkte

HTTP-Endpunkt aufrufen

Mit diesem Schritt können Sie eine HTTP-Anfrage stellen. Sowohl HTTP- als auch HTTPS-Anfragen werden unterstützt. Die gängigsten Methoden für HTTP-Anfragen haben eine Aufrufverknüpfung wie http.get und http.post. Sie können aber eine beliebige Methode verwenden, um Typ der HTTP-Anfrage. Dazu setzen Sie das Feld call auf http.request und geben den Anfragetyp im Feld method an.

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"
      }
    }
  ]
    

Dabei gilt:

• HTTP_REQUEST: erforderlich. Verwenden Sie eines der folgenden Formate für HTTP-Anfragen: <ph type="x-smartling-placeholder">
  </ph>
  • http.delete
  • http.get
  • http.patch
  • http.post
  • http.put
  • http.request
• URL_VALUE: erforderlich. URL, an die die Anfrage gesendet wird.
• REQUEST_METHOD: erforderlich bei Verwendung des Anruftyps http.request. Der zu verwendende HTTP-Anfragetyp. Beispiel:
  • GET
  • POST
  • PATCH
  • DELETE
• REGISTERED_SERVICE: Optional. Registrierte Person Service Directory-Dienstname im Format projects/PROJECT_ID/locations/LOCATION/namespaces/NAMESPACE_NAME/services/SERVICE_NAME Weitere Informationen finden Sie unter Eine VPC Service Controls-konformer privater Endpunkt.
• HEADER_KEY:HEADER_VALUE: optional. Header-Felder für die Bereitstellung der API

  Wenn Sie den Medientyp des Anfragetexts mit einem Content-Type-Header angeben, werden nur die folgenden Typen unterstützt:

  • application/json oder application/type+json – muss eine Karte sein
  • application/x-www-form-urlencoded: darf keine Codierung sein. String
  • text/type — muss ein String sein.

  Wenn ein Content-Type-Header angegeben ist, lautet der Textkörper wie vorgeschrieben codiert. Er kann beispielsweise JSON- oder URL-codiert sein.

  Wenn Sie einen User-Agent-Header verwenden, um den anfragenden User-Agent zu identifizieren, gilt Folgendes:

  • Die Standardeinstellung ist GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs)
  • Wenn ein Wert angegeben ist, GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs) an diesen Wert angehängt wird

    Wenn beispielsweise User-Agent: "MY_USER_AGENT_VALUE" angegeben ist, sieht der HTTP-Anfrageheader wie folgt aus (mit einem Leerzeichen zwischen dem angegebenen Wert und dem angehängten Standardwert):

    MY_USER_AGENT_VALUE GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs)

• BODY_KEY:BODY_VALUE: optional. Textfelder zur Bereitstellung einer Eingabe für die API

  Wenn kein Content-Type-Header angegeben ist und eine Anfrage Text vorhanden ist, gilt Folgendes:

  • Wenn der Textwert in Byte liegt, wird der Header auf Content-Type: application/octet-stream
  • Andernfalls ist der Text JSON-codiert und der Header ist auf Content-Type: application/json; charset=utf-8
  Das folgende Beispiel zeigt eine Textstruktur, die einer JSON-Nutzlast entspricht:

  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: optional. Abfragefelder zur Bereitstellung einer Eingabe für die API
• AUTH_TYPE: Optional. Erforderlich, wenn die aufgerufene API eine Authentifizierung erfordert. Verwenden Sie entweder OIDC oder OAuth2. Weitere Informationen finden Sie unter Authentifizierung durchführen Anfragen aus einem Workflow.
  • AUTH_SCOPE: Optional. Beschränkt die Zugriff auf das Konto eines Nutzers. Verwenden Sie entweder die Taste scope oder scopes.

    Der Schlüssel scope unterstützt entweder einen String oder eine Liste von Zeichenfolgen. Beispiel:

    "https://www.googleapis.com/auth/cloud-platform"

    oder

    ["https://www.googleapis.com/auth/cloud-platform", "scope2", "scope3"]

    Der scopes-Schlüssel, zusätzlich zur Unterstützung eines String oder Liste von Strings; unterstützt Leerzeichen und durch Kommas getrennte Strings. Beispiel:

    "https://www.googleapis.com/auth/cloud-platform scope2 scope3"

    oder

    "https://www.googleapis.com/auth/cloud-platform,scope2,scope3"

    Weitere Informationen finden Sie unter <ph type="x-smartling-placeholder"></ph> OAuth 2.0-Bereiche für Google APIs.

  • AUDIENCE: Optional. Gibt die Zielgruppe für das OIDC-Token. Standardmäßig ist es auf denselben Wert festgelegt wie url. Allerdings sollte sie auf die Stamm-URL Ihres Dienstes festgelegt sein. Hier einige Beispiele: https://region-project.cloudfunctions.net/hello_world
• TIMEOUT_IN_SECONDS: Optional. Dauer in Sekunden darf eine Anfrage ausgeführt werden, bevor eine Ausnahme ausgelöst wird. Die maximale Anzahl ist 1.800 Sekunden.
• RESULT_VALUE: Optional. Variablenname, in dem das Ergebnis eines HTTP-Aufrufschritts gespeichert ist.

Auf in einer Variable gespeicherte HTTP-Antwortdaten zugreifen

Wenn der Content-Type-Header für die Antwort ein application/json, also die JSON-Antwort, die in einem wird automatisch in eine Karte konvertiert, auf die zugegriffen werden kann.

Ändern Sie bei Bedarf die aufgerufene API, um ein application/json-Medientyp für Content-Type -Antwortheader. Andernfalls können Sie den json.decode und text.encode, um Antworttext in eine Map konvertieren. Beispiel:

json.decode(text.encode(RESPONSE_FROM_API))

Workflows enthalten einen integrierten Parser für den Zugriff auf diese Daten. Verwenden Sie die folgende Syntax, um über die HTTP-Antwort auf die Felder zuzugreifen:

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

Ersetzen Sie Folgendes:

• VARIABLE_NAME: der Name der Workflowvariablen, wobei haben Sie eine JSON-Antwort gespeichert.
• body: Verwenden Sie das Feld body, um auf den Text der HTTP-Antwort zuzugreifen.
• code: Verwenden Sie das Feld code, um auf den HTTP-Antwortcode zuzugreifen.
• headers: Verwenden Sie das Feld headers, um namentlich auf die HTTP-Antwortheader zuzugreifen.
• PATH_TO_FIELD: der Pfad zum Feld in der JSON-Datei auf die Sie zugreifen möchten. Das kann einfach der Name des Felds sein oder der Wert in einem Objekt verschachtelt ist, kann es die Form object1.object2.field haben.

Wenn eine API beispielsweise {"age":50} zurückgibt und ein Workflow diese Antwort in einer Variablen mit dem Namen age_response speichert, gibt das folgende Beispiel den Wert des Felds age zurück: In diesem Fall gilt 50:

age_response.body.age

Beispiele

Diese Beispiele veranschaulichen die Syntax.

Antwort von einem API-Aufruf zuweisen

Wenn Sie keinen eigenen Suchbegriff eingeben, wird in diesem Beispiel Ihr Google Cloud- Standort zum Erstellen eines Suchbegriffs, der an den Wikipedia API A wird eine Liste verwandter Wikipedia-Artikel zurückgegeben.

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]}"
        }
      }
    ]
  }
}

Externe HTTP-POST-Anfrage stellen

In diesem Beispiel wird eine POST-Anfrage an einen externen HTTP-Endpunkt gesendet.

YAML

- send_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

[
  {
    "send_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}"
    }
  }
]

Externe HTTP GET-Anfrage mit Headern senden

In diesem Beispiel wird eine HTTP GET-Anfrage mit einem benutzerdefinierten Header gesendet. Sie können auch benutzerdefinierte Headerdefinitionen festlegen, wenn Sie andere Arten von HTTP-Anfragen stellen.

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}"
    }
  }
]

OIDC zur Authentifizierung bei einer Anfrage an Cloud Functions verwenden

In diesem Beispiel wird eine HTTP-Anfrage mit OIDC durch Hinzufügen einerauth zumargs Abschnitt der Workflow-Definition, nachdem Sie die URL angegeben haben.

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}"
    }
  }
]

HTTP-Anfragefehler abfangen und verarbeiten

In diesem Beispiel wird ein benutzerdefinierter Ausnahme-Handler implementiert, der auf dem HTTP-Statuscode basiert. GET-Anfrage zurückgegeben. Der Workflow erkennt eine mögliche Ausnahme und gibt eine vordefinierte Fehlermeldung zurück. Wird eine Ausnahme nicht erkannt, Die Workflowausführung schlägt fehl und löst die Ausnahme aus, wie sie von der GET-Anfrage zurückgegeben wird. Informationen zu anderen Fehler-Tags finden Sie unter Workflowfehler:

YAML

# Use a custom exception handler to catch exceptions and return predefined
# error messages; if the exception isn't recognized, the workflow
# execution fails and throws the exception returned by the GET request
- 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"
    }
  }
]

Nächste Schritte

• Workflows mit Cloud Run und Cloud Functions verwenden
• VPC Service Controls-konformen privaten Endpunkt aufrufen
• Privaten lokalen Endpunkt, Compute Engine, GKE oder einen anderen Endpunkt durch Aktivieren von IAP aufrufen
• Referenz zur Workflows-Syntax