HTTP

HTTP コネクタは、HTTP サービスへの接続を提供し、HTTP ベースの API を使用します。このコネクタは、カスタム構成による SSL / TLS 接続をサポートし、OAuth 2.0 クライアント認証情報の付与、基本、ダイジェストなどのさまざまな認証メカニズムもサポートしています。

準備

HTTP コネクタを使用する前に、次の作業を行います。

  • Google Cloud プロジェクトで次の操作を行います。
    • コネクタを構成するユーザーに roles/connectors.admin IAM ロールを付与します。
    • コネクタに使用するサービス アカウントに、次の IAM ロールを付与します。
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor

      サービス アカウントは特別なタイプの Google アカウントで、Google API のデータにアクセスするのに認証を受ける必要がある人間以外のユーザーを表します。サービス アカウントがない場合は、サービス アカウントを作成する必要があります。詳細については、サービス アカウントを作成するをご覧ください。

    • 次のサービスを有効にします。
      • secretmanager.googleapis.com（Secret Manager API）
      • connectors.googleapis.com（Connectors API）

      サービスを有効にする方法については、サービスを有効にするをご覧ください。

    以前にプロジェクトでこうしたサービスを有効にしていない場合は、コネクタを構成するときにそれを有効にすることを求められます。

コネクタを構成する

コネクタを構成するには、データソース（バックエンド システム）への接続を作成する必要があります。接続はデータソースに特有です。つまり、多数のデータソースがある場合は、データソースごとに別々の接続を作成する必要があります。接続を作成する手順は次のとおりです。

  1. Cloud コンソールで、[Integration Connectors] > [接続] ページに移動し、Google Cloud プロジェクトを選択または作成します。

    [接続] ページに移動

  2. [+ 新規作成] をクリックして [接続の作成] ページを開きます。
  3. [ロケーション] セクションで、接続のロケーションを選択します。
    1. リージョン: プルダウン リストからロケーションを選択します

      サポートされているすべてのリージョンの一覧については、ロケーションをご覧ください。

    2. [次へ] をクリックします。
  4. [接続の詳細] セクションで、次の操作を行います。
    1. コネクタ: 使用可能なコネクタのプルダウン リストから [HTTP] を選択します。
    2. コネクタのバージョン: 使用可能なバージョンのプルダウン リストからコネクタのバージョンを選択します。
    3. [接続名] フィールドに、接続インスタンスの名前を入力します。

      接続名は次の条件を満たす必要があります。

      • 接続名には英字、数字、ハイフンを使用できます。
      • 文字は小文字のみを使用できます。
      • 接続名の先頭には英字を設定し、末尾には英字または数字を設定する必要があります。
      • 接続名は 63 文字以内で指定してください。
    4. 必要に応じて、接続インスタンスの [説明] を入力します。
    5. サービス アカウント: 必要なロールを持つサービス アカウントを選択します。
    6. 必要に応じて、接続ノードの設定を構成します。

      • ノードの最小数: 接続ノードの最小数を入力します。
      • ノードの最大数: 接続ノードの最大数を入力します。

      ノードは、トランザクションを処理する接続の単位（またはレプリカ）です。1 つの接続でより多くのトランザクションを処理するには、より多くのノードが必要になります。逆に、より少ないトランザクションを処理するには、より少ないノードが必要になります。ノードがコネクタの料金に与える影響については、接続ノードの料金をご覧ください。値を入力しない場合は、デフォルトで最小ノード数は 2 に設定され（可用性を高めるため）、最大ノード数は 50 に設定されます。

    7. プロキシの使用: 接続用のプロキシ サーバーを構成するために、このチェックボックスを選択します。
      1. [+ 宛先を追加] をクリックします。
      2. [Destination Type] を選択します。
        • Host address: 宛先のホスト名または IP アドレスを指定します。

          バックエンドへのプライベート接続を確立する場合は、次のようにします。

    8. 必要に応じて、[+ ラベルを追加] をクリックして Key-Value ペアの形式でラベルを接続に追加します。
    9. 必要に応じて SSL を使用する場合は、[SSL を有効にする] を選択します。これにより、SSL 構成の詳細が表示されます。
      1. トラストストアの種類を選択します。[パブリック]、[プライベート]、[安全でない接続] のいずれかになります。
      2. トラストストアの選択に基づいて表示される証明書を選択します。
      3. mTLS を使用している場合は、[Key Store] セクションでキーストア証明書を選択します。
      4. 必要に応じて、TLS のバージョンを選択します。
      5. サポートされている暗号スイートを入力します。複数の暗号スイートをカンマ区切りの値として入力します。詳細については、サポートされている暗号スイートをご覧ください。
    10. [次へ] をクリックします。
  5. [宛先] セクションに、接続するリモートホスト（バックエンド システム）の詳細を入力します。
    1. Destination Type: 宛先の種類を選択します。
      1. [ホストアドレス] フィールドに、宛先のホスト名または IP アドレスを指定します。
        1. バックエンド システムへのプライベート接続を確立する場合は、次のようにします。
          1. PSC サービス アタッチメントを作成します。
          2. エンドポイント アタッチメント作成してから、ホストアドレスフィールドにあるエンドポイント アタッチメントの詳細を入力します。
        2. セキュリティをさらに強化してバックエンドシステムへのパブリック接続を確立する場合は、接続用の静的送信 IP アドレスの構成を検討し、ファイアウォール ルールを構成することを検討してください。特定の静的 IP アドレスのみを許可リストに登録します。

      他の宛先を入力するには、[+ 宛先を追加] をクリックします。

    2. [次へ] をクリックします。
  6. [認証] セクションで、認証の詳細を入力します。
    1. [認証タイプ] を選択し、関連する詳細を入力します。

      HTTP 接続でサポートされる認証タイプは次のとおりです。

      2. これらの認証タイプの構成方法については、認証を構成するをご覧ください。

    2. [次へ] をクリックします。
  7. Review: 接続と認証の詳細を確認します。
  8. [作成] をクリックします。

認証を構成する

使用する認証に基づいて詳細を入力します。

  • カスタム認証

    カスタム承認の詳細は、コネクタタスクのアクション実行中に、リクエスト ヘッダーとして追加できます。

  • OAuth 2.0 - クライアント認証情報付与
    • Client ID: HTTP リクエストの認証に使用するクライアント ID。
    • Client Secret: HTTP リクエストを認証するためのクライアント シークレットを含む Secret Manager の Secret。
    • アクセス トークン用のリクエスト形式: 認証サーバーからアクセス トークンを取得するために行われるリクエストで使用されるリクエスト形式。 クライアント ID と Secret をリクエスト本文として渡すには body を選択し、それらをエンコードされたヘッダーとして渡すには header を選択します。
    • Token Request Path: アクセス トークンの URL を取得するために認証サーバーの URL に追加するリクエストパス。
    • デフォルトの有効期限: アクセス トークンのデフォルトの有効期限（秒単位）。この時間は、アクセス トークンのレスポンスに有効期限がない場合に使用されます。値が指定されていない場合、トークンは 6 時間以内に更新されます。
  • 基本認証
    • Username: HTTP リクエストを行うために使用されるユーザー名。
    • Password: 指定されたユーザー名に関連付けられたパスワードを含む Secret Manager の Secret。
  • ダイジェスト認証
    • Username: HTTP リクエストを行うために使用されるユーザー名。
    • Password: 指定されたユーザー名に関連付けられたパスワードを含む Secret Manager の Secret。
  • OAuth 2.0 - 認証コード
    • クライアント ID: 外部アプリケーションによって提供されるクライアント ID。
    • スコープ: 外部アプリケーションでサポートされている権限のスコープ。
    • クライアント シークレット: Secret Manager のシークレットを選択します。 この認証を構成する前に、Secret Manager のシークレットを作成しておく必要があります。
    • シークレットのバージョン: クライアント シークレットの Secret Manager シークレットのバージョン。
    • バックエンド サーバーがサポートしている場合は、必要に応じて PKCE（Proof Key for Code Exchange）を有効にします。
    • 認証 URL: 外部アプリケーションの承認 URL を入力します。
    • アクセス トークン URL: 外部アプリケーションのアクセス トークンを取得するための URL を入力します。

    Authorization code 認証タイプの場合は、接続を作成した後、認証を構成するためにいくつかの追加手順を行う必要があります。詳しくは、接続作成後の追加手順をご覧ください。

  • サービス アカウント

    この接続を構成するときに前の手順で指定したサービス アカウントを使用して認証するには、このオプションを選択します。サービス アカウントに、認証に必要な IAM ロールと権限が付与されていることを確認してください。

    • スコープ: 必要なカンマ区切りのアクセス スコープを入力します。詳細については、アクセス スコープをご覧ください。
  • サービス アカウント ID トークン認証

    前の手順で指定したサービス アカウントから生成された ID トークンを使用して認証するには、このオプションを選択します。この認証では、認証に JSON ウェブトークン（JWT）を使用します。ID トークン プロバイダは、サービス アカウントを使用して認証を行うために JWT に署名し、発行します。

    • オーディエンス: JWT の受取人を入力します。
    • ヘッダー名: HTTP ヘッダーで使用する生成された ID トークンのヘッダー名を入力します。このフィールドに値を指定しない場合、キー値はデフォルトで Authorization に設定されます。
  • API キー認証

    API キーを使用して認証するには、このオプションを選択します。

    • API キー: API キーの Secret Manager の Secret を選択します。
    • シークレットのバージョン: シークレットのバージョンを選択します。
    • API キーのパラメータ名: API キーのパラメータ名を入力します。API キーは Key-Value ペアとしてバックエンド サーバーに送信されます。ここに入力する値は、前に選択した API キーのキー名として使用されます。
    • API キーのロケーション: リクエスト内で API キーを追加する場所を選択します。

サポートされている暗号スイート

TLS バージョン サポートされている暗号スイート
1.2
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
1.3
  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256
  • TLS_AES_128_GCM_SHA256

接続作成後の追加手順

認証に OAuth 2.0 - Authorization code を選択した場合は、接続の作成後に次の追加の手順を行う必要があります。

  1. 接続ページで、新しく作成された接続を見つけます。

    新しいコネクタの [ステータス] は [承認が必要] になります。

  2. [承認が必要] をクリックします。

    これにより、[承認の編集] ペインが表示されます。

  3. [リダイレクト URI] の値を外部アプリケーションにコピーします。
  4. 認可の詳細を確認します。
  5. [Authorize（承認）] をクリックします。

    認可が成功すると、[接続] ページの接続ステータスが「有効」に設定されます。

認証コードの再認可

Authorization code 認証タイプを使用しているユーザーが、バックエンド HTTP アプリケーションの構成を変更した場合は、HTTP 接続を再認可する必要があります。接続を再認可するには、次の手順を行います。

  1. [接続] ページで必要な接続をクリックします。

    これにより、[接続の詳細] ページが開きます。

  2. [編集] をクリックして、接続の詳細を編集します。
  3. [認証] セクションで [OAuth 2.0 - 認証コード] の詳細を確認します。

    必要に応じて必要な変更を加えます。

  4. [Save] をクリックします。接続の詳細ページに移動します。
  5. [認証] セクションで [承認の編集] をクリックします。これにより、[承認] ペインが表示されます。
  6. [Authorize（承認）] をクリックします。

    認可が成功すると、[接続] ページの接続ステータスが「有効」に設定されます。

エンティティ、オペレーション、アクション

すべての Integration Connectors が、接続されたアプリケーションのオブジェクトを抽象化するレイヤを提供します。アプリケーションのオブジェクトには、この抽象化を通じてのみアクセスできます。抽象化は、エンティティ、オペレーション、アクションとして公開されます。

  • エンティティ: エンティティは、接続されているアプリケーションやサービスのオブジェクト、またはプロパティのコレクションと考えることができます。エンティティの定義は、コネクタによって異なります。たとえば、データベース コネクタでは、テーブルがエンティティであり、ファイル サーバー コネクタでは、フォルダがエンティティです。また、メッセージング システム コネクタでは、キューがエンティティです。

    ただし、コネクタでいずれのエンティティもサポートされていない、またはエンティティが存在しない可能性があります。その場合、Entities リストは空になります。

  • オペレーション: エンティティに対して行うことができるアクティビティです。エンティティに対して次のいずれかのオペレーションを行うことができます。

    使用可能なリストからエンティティを選択すると、そのエンティティで使用可能なオペレーションのリストが生成されます。オペレーションの詳細については、コネクタタスクのエンティティ オペレーションをご覧ください。ただし、コネクタがどのエンティティ オペレーションもサポートしていない場合、サポートされていないオペレーションは Operations リストに表示されません。

  • アクション: コネクタ インターフェースを介して統合で使用できる最初のクラス関数です。アクションを使用すると、1 つまたは複数のエンティティに対して変更を加えることができます。また、使用できるアクションはコネクタごとに異なります。ただし、コネクタがどのアクションもサポートしていない可能性があります。その場合は、Actions リストが空になります。

システムの上限

HTTP コネクタは、ノードごとに 1 秒あたり 100 件のトランザクションを処理し、この上限を超えるトランザクションをスロットルできます。デフォルトでは、Integration Connectors は、接続に 2 つのノードを割り当てます（可用性を高めるため）。

Integration Connectors に適用される上限の詳細については、上限をご覧ください。

サポートされているアクション

HTTP コネクタでは、次のアクションがサポートされています。

HttpRequest アクション

次の表に、HttpRequest アクションの入出力パラメータを示します。

HttpRequest アクションの入力パラメータ

パラメータ名 データ型 必須 説明
URL 構造体 いいえ リクエストを送信する対象の URL。URL は <scheme>://<netloc>/<path>;<params>?<query>#<fragment> 形式です。netloc を指定すると、接続の作成中に指定されたホスト名がオーバーライドされます。
メソッド String いいえ GET、POST、DELETE、PUT などの HTTP リクエスト メソッド。デフォルト値は GET です。
ヘッダー 構造体 いいえ HTTP リクエスト ヘッダー。
本文 String いいえ HTTP リクエスト本文。
RequestHasBytes ブール値 いいえ リクエストをバイトとして送信するかどうか。true に設定した場合、Body パラメータで、Base64 でエンコードされた文字列としてリクエストを送信する必要があります。デフォルト値は false です。
ResponseHasBytes ブール値 いいえ レスポンスをバイトとして受信するかどうか。true に設定すると、ResponseBody 出力パラメータで Base64 エンコード文字列としてレスポンスを受信します。デフォルト値は false です。
HttpVersion String いいえ リクエストを行う際に使用する HTTP バージョン。サポートされている値は 1.1 と 2 です。バージョン 2 を指定すると、ALPN（アプリケーション レイヤ プロトコル ネゴシエーション）ネゴシエーションが行われ、サーバーがバージョン 2 をサポートしていない場合はバージョン 1.1 が使用されます。デフォルト値は 2 です。
ResponseFormat 文字列 いいえ コネクタからのレスポンスの形式を指定します。サポートされている値は v1 と v2 です。 デフォルト値は v1 です。

v1 レスポンスの例:

[{
"ResponseBody": "{\n \"status\": 200\n}"
}, {
"StatusCode": 200.0
}, {
"HttpVersion": "2"
}, {
"ResponseHeaders": {
":status": "200",
"content-length": "19"
}
}]

v2 レスポンスの例:

[{
"ResponseBody": "{\n \"status\": 200\n}",
"StatusCode": 200.0,
"HttpVersion": "2",
"ResponseHeaders": {
":status": "200",
"content-length": "19"
}
}]
FailOnError ブール値 いいえ バックエンド アプリケーションにエラーがある場合の接続の動作を指定します。
  • true - 例外をスローします。バックエンドによってスローされた例外は、接続のレスポンスに伝播されます。
  • false - 例外はスローしません。ただし、レスポンスでエラーコードとエラー メッセージが返されます。

デフォルト値は true です。
タイムアウト Integer × HTTP リクエストのタイムアウト値（秒単位）。最大許容値は 150 秒です。

HttpRequest アクションの出力パラメータ

パラメータ名 データ型 説明
ResponseBody String HTTP サーバーから受信したレスポンス。
StatusCode Integer HTTP サーバーから受信したステータス コード。
HttpVersion String HTTP リクエスト用にネゴシエートされたバージョン。
ResponseHeaders 構造体 key,value ペアの形式の HTTP レスポンス ヘッダー。

例

このセクションの例では、次のオペレーションについて説明します。

  • リクエストのペイロードを構成する
  • バイト コンテンツを送信する
  • バイト コンテンツを取得する

次の表では、コネクタのタスクのサンプル シナリオと対応する構成を示します。

タスク 構成
リクエストのペイロードを構成する
  1. [Configure connector task] ダイアログで、[Actions] をクリックします。
  2. [HttpRequest] アクションを選択してから、[完了] をクリックします。
  3. [コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
    {
  "Url": {
    "scheme": "https",
    "netloc": "httpbin.org",
    "path": "post",
    "query": "example=A&sort=value",
    "fragment": "exampleFragment"
  },
  "Method": "POST",
  "Headers": {
    "Accept": ["application/json", "application/xml"],
    "a": "b"
  },
  "Body": "{\"thisIsRequestJSON\":\"someValue\"}"
}
  4. [保存] をクリックします。

この例では、https://httpbin.org/post?example=A&=value#exampleFragment URL に POST リクエストを行います。そして、netloc がペイロードで指定されるため、接続の作成中に指定されたホスト名がオーバーライドされます。
バイト コンテンツを送信する

次の例に示すとおり、バイト（ファイルなど）コンテンツを送信するには、RequestHasBytes リクエスト属性を true に設定し、送信する Base64 でエンコードされた文字列に body 属性を設定する必要があります。

  1. [Configure connector task] ダイアログで、[Actions] をクリックします。
  2. [HttpRequest] アクションを選択してから、[完了] をクリックします。
  3. [コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
    {
  "Url": {
    "scheme": "https",
    "netloc": "httpbin.org",
  },
  "Method": "POST",
  "Headers": {
    "Accept": ["application/json", "application/xml"],
    "a": "b"
  },
  "Body": "SGVsbG8gV29ybGQ=",
  "RequestHasBytes":true
}
  4. [保存] をクリックします。

この例では、POST リクエストを httpbin.org サーバーに送信し、リクエストの本文で Base64 エンコード文字列の形式でファイルの内容を送信します。サーバーは、ファイル内容の処理方法を決定できます。
バイト コンテンツを取得する

サーバーから（Base64 文字列として）バイトを取得するには、次のサンプルに示すように ResponseHasBytes リクエスト属性を true に設定する必要があります。

  1. [Configure connector task] ダイアログで、[Actions] をクリックします。
  2. [HttpRequest] アクションを選択してから、[完了] をクリックします。
  3. [コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
    {
  "Url": {
    "scheme": "https",
    "netloc": "httpbin.org",
  },
  "Method": "GET",
  "ResponseHasBytes":true
}
  4. [保存] をクリックします。

この例では、httpbin.org サーバーに対して GET リクエストを行い、リクエスト本文で ResponseHasBytes を true に設定します。

エラーコード

このセクションでは、HTTP 接続の使用時に受け取る場合のあるエラー メッセージについて説明します。

エラー メッセージ 原因
HTTP サーバーとの接続エラー SSL handshake に失敗した、または HTTP サーバー エンドポイントが正しくないため、HTTP 接続でサーバーとの接続の確立に失敗しました。
HTTP サーバーから受信したエラー レスポンス 接続しようとしている HTTP サーバーは、ステータス コード 4xx または 5xx のエラー レスポンスを返します。レスポンスの例: 
{
  "error": {
    "code": 400,
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "metadata": {
          "Body": "{\"thisIsResponseJSON\":\"someValue\"}"
          "Error": "Error response received from the HTTP server",
          "Headers": "{\":status\":[\"400\"], \"access-control-allow-credentials\":[\"true\"]}",
          "StatusCode": "400",
          "connection_type": "Http"
        }
      }
    ],
    "message": "Unable to execute HTTP Request",
    "status": "FAILED_PRECONDITION"
  }
}
アクセス トークンの取得中のエラー OAuth Client Credentials Grant 認証タイプ用のアクセス トークンを取得する際にエラーが発生しました。
Digest Auth のエラー コネクタ ランタイムがダイジェスト チャレンジを受信していないか、チャレンジがサポートされていないタイプです。

Terraform を使用して接続を作成する

Terraform リソースを使用して、新しい接続を作成できます。

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。

接続作成用の Terraform テンプレートのサンプルを表示するには、サンプル テンプレートをご覧ください。

Terraform を使用してこの接続を作成する場合は、Terraform 構成ファイルで次の変数を設定する必要があります。

パラメータ名 データ型 必須 説明
proxy_enabled BOOLEAN False 接続用のプロキシ サーバーを構成するには、このチェックボックスをオンにします。

統合で HTTP 接続を使用する

接続を作成すると、Apigee Integration と Application Integration の両方で使用できるようになります。この接続は、コネクタタスクを介して統合で使用できます。

  • Apigee Integration で Connectors タスクを作成して使用する方法については、Connectors タスクをご覧ください。
  • Application Integration で Connectors タスクを作成して使用する方法については、Connectors タスクをご覧ください。

Google Cloud コミュニティの助けを借りる

Google Cloud コミュニティの Cloud フォーラムで質問を投稿したり、このコネクタについてディスカッションしたりできます。

次のステップ