APIを使用したApp Connectorの管理

この記事では、APIを使用したZscaler Private Access (ZPA) App Connectorの管理について説明します。すべてのAPIはレート制限されています。詳細は、「レート制限について」を参照してください。

特定の App Connector の詳細を確認する

特定の App Connector の詳細を確認するには:

  1. コネクター コントローラー内の次のエンドポイントに GET リクエストを送信します: /mgmtconfig/v1/admin/customers/{customerId}/connector/{connectorId}
  2. リクエストエンドポイントに以下を提供します。
  • [customerId]:顧客のZPAテナントIDです。
  • connectorId: 顧客の App Connector ID。

例:/mgmtconfig/v1/admin/customers/217246660302995456/connector/2172466603024871.

  • {
      "id": "217246660303024871",
      "modifiedTime": "1617841545",
      "creationTime": "1617841545",
      "modifiedBy": "-2",
      "name": "example_provising_key-2",
      "fingerprint": "TQ0iesqrg2CwSD/CyyP/Tdb4XpEid0o/c8v9yTiJZVE=",
      "issuedCertId": "10723",
      "enabled": true,
      "upgradeAttempt": "0",
      "location": "British Columbia, Canada",
      "provisioningKeyId": "6211",
      "provisioningKeyName": "example_provising_key",
      "enrollmentCert": {
        "id": "2858",
        "name": "Mock Company Root Certificate"
      },
      "appConnectorGroupId": "217246660303024864",
      "appConnectorGroupName": "example_connector_group"
    } 
    閉じる

正常なレスポンスは、コード200が返されます。詳細は、API応答コードとエラー メッセージ を参照してください。

すべての App Connector の詳細を確認する

すべての App Connector の詳細を確認するには:

  1. コネクター コントローラー内の次のエンドポイントに GET リクエストを送信します:/mgmtconfig/v1/admin/customers/{customerId}/connector
  2. リクエストエンドポイントに、カスタマーID、顧客のZPAテナントIDを指定します。例:/mgmtconfig/v1/admin/customers/217246660302995456/connector.
  •  {
      "totalPages": "168",
      "list": [
        {
          "id": "217246660303024865",
          "modifiedTime": "1617747782",
          "creationTime": "1617747781",
          "modifiedBy": "-2",
          "name": "example_provising_key-1",
          "fingerprint": "ypAytG0R89+86b/HJEP3C86SJNiEjKLMXZGi7UzC070=",
          "issuedCertId": "10718",
          "enabled": true,
          "currentVersion": "21.67.2-5-gc17a10071-dirty",
          "upgradeStatus": "UNKNOWN",
          "controlChannelStatus": "ZPN_STATUS_DISCONNECTED",
          "upgradeAttempt": "0",
          "lastBrokerConnectTime": "1617750694",
          "lastBrokerConnectTimeDuration": "132d 19h 50m 43s",
          "lastBrokerDisconnectTime": "1617751234",
          "lastBrokerDisconnectTimeDuration": "132d 19h 41m 43s",
          "platform": "osx20",
          "latitude": "53.7266683",
    "longitude": "-127.647621",
    "location": "British Columbia, Canada",
          "provisioningKeyId": "6211",
          "provisioningKeyName": "example_provising_key",
          "enrollmentCert": {
            "id": "2858",
            "name": "Mock Company Root Certificate"
          },
          "appConnectorGroupId": "217246660303024864",
          "appConnectorGroupName": "example_connector_group"
        },
        {
          "id": "217246660303024871",
          "modifiedTime": "1617841545",
          "creationTime": "1617841545",
          "modifiedBy": "-2",
          "name": "example_provising_key-2",
          "fingerprint": "TQ0iesqrg2CwSD/CyyP/Tdb4XpEid0o/c8v9yTiJZVE=",
          "issuedCertId": "10723",
          "enabled": true,
          "upgradeAttempt": "0",
          "location": "British Columbia, Canada",
          "platformDetail": "ESXi",
          "provisioningKeyId": "6211",
          "provisioningKeyName": "example_provising_key",
          "enrollmentCert": {
            "id": "2858",
            "name": "Mock Company Root Certificate"
          },
          "appConnectorGroupId": "217246660303024864",
          "appConnectorGroupName": "example_connector_group"
        }
      ]
    }
    閉じる

正常なレスポンスは、コード200が返されます。詳細は、API応答コードとエラー メッセージ を参照してください。

ZPA Public Service Edge に最後に接続された App Connector を検索するには、search=lastBrokerConnectTimeDuration LT (N) を使用します。(N) は整数の日数 (d)、時間 (h)、分 (m)、秒 (s) を表します。

ZPA Public Service Edge から最後に切断されたすべての App Connector を検索するには、search=lastBrokerDisconnectTimeDuration LT (N) を使用します。(N) は整数の日数 (d)、時間 (h)、分 (m)、秒 (s) を表します。

たとえば、150 日以内に ZPA Public Service Edge に最後に接続された App Connectorを検索するには、 search=lastBrokerConnectTimeDuration LT 150d を使用します。

searchパラメータで使用できるフィルターは以下の通りです。

  • lastBrokerConnectTimeDuration: ZPA Public Service Edge に最後に接続された App Connector のフィルター。
  • lastBrokerDisconnectTimeDuration: ZPA Public Service Edge から最後に切断された App Connector のフィルター。
  • controlChannelStatus: 非アクティブな App Connector のフィルター。
  • currentVersion: App Connector の現在のバージョンのフィルター。
  • expectedVersion: 関連付けられたバージョン プロファイルに基づく App Connector の予想されるバージョンのフィルター。

たとえば、最後の切断時刻が (N) 日を超える、切断された controlChannelStatus を備えた App Connector を検索するには、controlChannelStatus EQ ZPN_STATUS_DISCONNECTED AND lastBrokerDisconnectTimeDuration GT 15d を使用します。

  • {
      "totalPages": "128",
      "list": [
        {
          "id": "217246660303024865",
          "modifiedTime": "1617747782",
          "creationTime": "1617747781",
          "modifiedBy": "-2",
          "name": "example_provising_key-1",
          "fingerprint": "ypAytG0R89+86b/HJEP3C86SJNiEjKLMXZGi7UzC070=",
          "issuedCertId": "10718",
          "enabled": true,
          "currentVersion": "21.67.2-5-gc17a10071-dirty",
          "upgradeStatus": "UNKNOWN",
          "controlChannelStatus": "ZPN_STATUS_DISCONNECTED",
          "upgradeAttempt": "0",
          "lastBrokerConnectTime": "1617750694",
          "lastBrokerConnectTimeDuration": "181d 13h 38m 46s",
          "lastBrokerDisconnectTime": "1617751234",
          "lastBrokerDisconnectTimeDuration": "181d 13h 29m 46s",
          "platform": "osx20",
          "latitude": "53.7266683",
    "longitude": "-127.647621",
    "location": "British Columbia, Canada",
          "provisioningKeyId": "6211",
          "provisioningKeyName": "example_provising_key",
          "enrollmentCert": {
            "id": "2858",
            "name": "Mock Company Root Certificate"
          },
          "appConnectorGroupId": "217246660303024864",
          "appConnectorGroupName": "example_connector_group"
        },
        {
          "id": "217246660303025075",
          "modifiedTime": "1622502016",
          "creationTime": "1622502016",
          "modifiedBy": "-2",
          "name": "example_provising_key-4",
          "fingerprint": "TkL50KRJxbkaCEOLtkS/Exv9qeUoHcuMtTHfr/gS8FQ=",
          "issuedCertId": "10766",
          "enabled": true,
          "currentVersion": "21.172.1-703-g4f9451e18",
    "previousVersion": "21.172.1-703-g9cedf7b87-dirty",
    "lastUpgradeTime": "1628190895",
          "upgradeStatus": "UNKNOWN",
          "controlChannelStatus": "ZPN_STATUS_DISCONNECTED",
          "upgradeAttempt": "0",
          "lastBrokerConnectTime": "1628206943",
          "lastBrokerConnectTimeDuration": "60d 13h 07m 56s",
          "lastBrokerDisconnectTime": "1628209139",
          "lastBrokerDisconnectTimeDuration": "60d 12h 31m 21s",
          "platform": "osx20",
          "latitude": "53.7266683",
    "longitude": "-127.647621",
    "location": "British Columbia, Canada",
          "platformDetail": "ESXi",
          "provisioningKeyId": "6211",
          "provisioningKeyName": "example_provising_key",
          "enrollmentCert": {
            "id": "2858",
            "name": "Mock Company Root Certificate"
          },
          "appConnectorGroupId": "217246660303024864",
          "appConnectorGroupName": "example_connector_group"
        }
      ]
    }
    {
      "totalPages": "128",
      "list": [
        {
          "id": "217246660303024865",
          "modifiedTime": "1617747782",
          "creationTime": "1617747781",
          "modifiedBy": "-2",
          "name": "example_provising_key-1",
          "fingerprint": "ypAytG0R89+86b/HJEP3C86SJNiEjKLMXZGi7UzC070=",
          "issuedCertId": "10718",
          "enabled": true,
          "currentVersion": "21.67.2-5-gc17a10071-dirty",
          "upgradeStatus": "UNKNOWN",
          "controlChannelStatus": "ZPN_STATUS_DISCONNECTED",
          "upgradeAttempt": "0",
          "lastBrokerConnectTime": "1617750694",
          "lastBrokerConnectTimeDuration": "181d 13h 38m 46s",
          "lastBrokerDisconnectTime": "1617751234",
          "lastBrokerDisconnectTimeDuration": "181d 13h 29m 46s",
          "platform": "osx20",
          "latitude": "53.7266683",
    "longitude": "-127.647621",
    "location": "British Columbia, Canada",
          "provisioningKeyId": "6211",
          "provisioningKeyName": "example_provising_key",
          "enrollmentCert": {
            "id": "2858",
            "name": "Mock Company Root Certificate"
          },
          "appConnectorGroupId": "217246660303024864",
          "appConnectorGroupName": "example_connector_group"
        },
        {
          "id": "217246660303025075",
          "modifiedTime": "1622502016",
          "creationTime": "1622502016",
          "modifiedBy": "-2",
          "name": "example_provising_key-4",
          "fingerprint": "TkL50KRJxbkaCEOLtkS/Exv9qeUoHcuMtTHfr/gS8FQ=",
          "issuedCertId": "10766",
          "enabled": true,
          "currentVersion": "21.172.1-703-g4f9451e18",
    "previousVersion": "21.172.1-703-g9cedf7b87-dirty",
    "lastUpgradeTime": "1628190895",
          "upgradeStatus": "UNKNOWN",
          "controlChannelStatus": "ZPN_STATUS_DISCONNECTED",
          "upgradeAttempt": "0",
          "lastBrokerConnectTime": "1628206943",
          "lastBrokerConnectTimeDuration": "60d 13h 07m 56s",
          "lastBrokerDisconnectTime": "1628209139",
          "lastBrokerDisconnectTimeDuration": "60d 12h 31m 21s",
          "platform": "osx20",
          "latitude": "53.7266683",
    "longitude": "-127.647621",
    "location": "British Columbia, Canada",
          "provisioningKeyId": "6211",
          "provisioningKeyName": "example_provising_key",
          "enrollmentCert": {
            "id": "2858",
            "name": "Mock Company Root Certificate"
          },
          "appConnectorGroupId": "217246660303024864",
          "appConnectorGroupName": "example_connector_group"
        }
      ]
    }
    閉じる

以下のルールタグの操作が可能である。

  • GT: より大きい
  • LT: 未満
  • GTEQ :以上であること。
  • LTEQ: 以下とする。

本APIはページネーションに対応しています。ページ分割されたレスポンスを取得する手順は次のとおりです。

  1. コネクター コントローラー内の次のエンドポイントに GET リクエストを送信します:/mgmtconfig/v1/admin/customers/{customerId}/connector?page=1&pagesize=20
  2. リクエストエンドポイントに以下を提供します。
  • [customerId]:顧客のZPAテナントIDです。
  • ページおよびページサイズのパラメータに有効な値。

例えば、/mgmtconfig/v1/admin/customers/217246660302995456/connector?page=1&pagesize=20です。

  • {
      "totalPages": "1",
      "list": [
        {
          "id": "144118148382064836",
          "modifiedTime": "1621702841",
          "creationTime": "1499716060",
          "modifiedBy": "-2",
          "name": "Azure Connector-1",
          "fingerprint": "Ic7rJNG6HQvjQ7EJj0uR76WBpm6mtCe3JCrLw91WmXE=",
          "issuedCertId": "258586",
          "enabled": true,
          "expectedVersion": "22.73.4",
          "currentVersion": "22.73.4",
          "previousVersion": "22.48.2",
          "lastUpgradeTime": "1647708745",
          "upgradeStatus": "COMPLETE",
          "controlChannelStatus": "ZPN_STATUS_AUTHENTICATED",
          "upgradeAttempt": "0",
          "ctrlBrokerName": "US-CA-9396",
          "lastBrokerConnectTime": "1649128946",
          "lastBrokerConnectTimeDuration": "17h 32m 50s",
          "sargeVersion": "17.20.2",
    "lastBrokerDisconnectTime": "1649128888",
          "lastBrokerDisconnectTimeDuration": "17h 33m 48s",
          "privateIp": "10.0.0.4",
          "publicIp": "10.0.0.1",
          "プラットフォーム": "el7",
          "applicationStartTime": "1647708745",
          "緯度": "36.778261",      "longitude": "-119.417932",
    "location": "California, USA",
          "platformDetail": "Azure",
          "provisioningKeyId": "554",
          "provisioningKeyName": "Azure Connector",
          "enrollmentCert": {
            "id": "117",
            "name": "Connector"
          },
          "appConnectorGroupId": "144118148382064835",
          "appConnectorGroupName": "Azure Connectors"
        },
        {
          "id": "144118148382065437",
          "modifiedTime": "1621702855",
          "creationTime": "1591139746",
          "modifiedBy": "-2",
          "name": "*Do not Delete* Lanukcorp AWS Connectors-4",
          "fingerprint": "Gvyg1hnlredGtyt7EWyLVRlyinXmXZnknbAfM9lClf4=",
          "issuedCertId": "258589",
          "enabled": true,
          "expectedVersion": "22.73.4",
          "currentVersion": "22.73.4",
          "previousVersion": "22.48.2",
          "lastUpgradeTime": "1647708563",
          "upgradeStatus": "COMPLETE",
          "controlChannelStatus": "ZPN_STATUS_AUTHENTICATED",
          "upgradeAttempt": "0",
          "ctrlBrokerName": "US-WA-0317",
          "lastBrokerConnectTime": "1649062642",
          "lastBrokerConnectTimeDuration": "01d 11h 57m 54s",
          "sargeVersion": "18.66.2",
          "lastBrokerDisconnectTime": "1647708499",
          "lastBrokerDisconnectTimeDuration": "17d 04h 06m 57s",
          "privateIp": "10.0.1.108",
    "publicIp": "52.222.36.1",
          "platform": "el7",
          "applicationStartTime": "1647711424",
          "latitude": "45.3573429",
    "longitude": "-122.606758",
    "location": "Oregon City, OR 97045, USA",
          "provisioningKeyId": "154",
          "provisioningKeyName": "*Do not Delete* Lanukcorp AWS Connectors",
          "enrollmentCert": {
            "id": "117",
            "name": "Connector"
          },
          "appConnectorGroupId": "144118148382064655",
          "appConnectorGroupName": "AWS Assistants"
        }
      ]
    }
    閉じる

提供されない場合、デフォルトのページサイズは20です。最大ページサイズは500です。

正常なレスポンスは、コード200が返されます。詳細は、API応答コードとエラー メッセージ を参照してください。

このAPIは、機能とフィールドで検索する検索オプションをサポートしています。機能とフィールドで検索する手順は次の通りです。

  1. 次のエンドポイントに GET リクエストを送信します: /mgmtconfig/v1/admin/customers/73186051597795328/connector&search={searchString}
  2. リクエストエンドポイントに以下を提供します。
  • [customerId]:顧客のZPAテナントIDです。
  • 有効な検索文字列値。検索文字列の値は fieldName operator fieldValue の形式です。有効なフィールドとフィルターの値に対応する検索文字列の値のみがサポートされています。たとえば、%EQ%true対応 文字列は、Status フィルター用に、Equals (EQ) 演算子を使用してサポートされています (True (Enabled) フィルター値)。

例: /mgmtconfig/v1/admin/customers/73186051597795328/connector&search=enabled%20EQ%20true

  • {
      "totalPages": "16",
      "totalCount": "16",
      "list": [
        {
          "id": "72057594038053055",
          "modifiedTime": "1662757554",
          "creationTime": "1633089623",
          "modifiedBy": "72057594038058534",
          "name": "Example App Connector",
          "description": "Example description",
          "fingerprint": "ZWM5OWM1ODcwMzcxMDJmOGY2Mzc3YjE5NjUyODJhOGUyZTAwNWMwZjhkN2",
          "enabled": true,
          "upgradeAttempt": "0",
          "location": "1234 Example Location",
          "microtenantName": "Default",
          "provisioningKeyId": "8588",
          "provisioningKeyName": "Abct",
          "appConnectorGroupId": "72057594038009372",
          "appConnectorGroupName": "Example App Connector Group"
        }
      ]
    }
    
    閉じる

ZPA APIポータルまたはリファレンス ガイドを使用してAPIコールを行う場合、検索フィールド文字列に文字は必要ありません。たとえば、enabled%20EQ%20trueenabled EQ trueです。

正常なレスポンスは、コード200が返されます。詳細は、API応答コードとエラー メッセージ を参照してください。

App Connector の更新

App Connector を更新するには:

  1. コネクター コントローラー内の次のエンドポイントに PUT リクエストを送信します: /mgmtconfig/v1/admin/customers/{customerId}/connector/{connectorId}
  2. リクエストエンドポイントに以下を提供します。
  • [customerId]:顧客のZPAテナントIDです。
  • connectorId: 顧客の App Connector ID。

例:/mgmtconfig/v1/admin/customers/217246660302995456/connector/2172466603024871.

  1. 次の JSON ペイロードを使用して App Connector を更新し、 App Connector に関する次の情報を提供します:
  • name: App Connector の名前。
  • description: App Connector の説明。
  • enabled: App Connector が有効になっているかどうか。

対応する値については、フィールド説明の追加セクションを参照してください。

レスポンスが成功すると、App Connectorが更新されたことを意味するコード204が生成されます。詳細は、「APIレスポンス コードとエラー メッセージ」を参照してください。

App ConnectorがZscaler デセプションを使用して設定されている場合、更新オプションと削除オプションは使用できません。

フィールド説明の追加

次のテーブルには、App Connectorのユース ケース用に使用できるフィールドが含まれています。

フィールド説明必須
nameApp Connector の名前いいえ文字列
説明App Connector の説明いいえ文字列
有効App Connector が有効になっているかどうかいいえ

[デフォルト]:true

[対応する値]:truefalse

マイクロテナント IDZPAテナントのマイクロテナントの一意の識別子。マイクロテナント内にいる場合は、そのマイクロテナントからデータを取得するAPIコールを行うときにmicrotenantIdフィールドを渡す必要があります。microtenantIdは[APIキー]ページで取得することも、ZPA クラウドサービスAPIを使用してプログラムで取得することもできます。マイクロテナント内にいる場合、特定の操作へのアクセスは制限されます。デフォルト マイクロテナント内にいる場合は、デフォルト マイクロテナントからデータを取得するリクエストを行うときにmicrotenantId0として渡します。microtenantIdをnullとして渡すと、テナントに関連付けられているすべてのマイクロテナントからデータが取得されます。リソースを作成または更新する時にmicrotenantIdがリクエストで渡されない場合、リソースはデフォルト マイクロテナントで作成または更新されます。詳細は、「APIを使用したマイクロテナントの設定」を参照してください。いいえ整数

App Connector の削除

App Connector を削除するには:

  1. コネクター コントローラー内の次のエンドポイントに DELETE リクエストを送信します: /mgmtconfig/v1/admin/customers/{customerId}/connector/{connectorId}
  2. リクエストエンドポイントに以下を提供します。
  • [customerId]:顧客のZPAテナントIDです。
  • connectorId: 顧客の App Connector ID。

例:/mgmtconfig/v1/admin/customers/217246660302995456/connector/2172466603024871.

レスポンスが成功すると、App Connectorが削除されることを意味するコード204が生成されます。詳細は、「APIレスポンス コードとエラー メッセージ」を参照してください。

App ConnectorがZscaler デセプションを使用して設定されている場合、更新オプションと削除オプションは使用できません。

App Connector の一括削除

App Connector を一括削除するには:

  1. 一括削除する App Connector ID を次の JSON ペイロードに指定し、コネクター コントローラー内の次のエンドポイントに POST リクエストを送信します: /mgmtconfig/v1/admin/customers/{customerId}/connector/bulkDelete
  1. 要求エンドポイントで、顧客のZPAテナントIDであるcustomerIdを指定します。例えば、/mgmtconfig/v1/admin/customers/217246660302995456/connector/bulkDeleteです。

レスポンスが成功すると、App Connectorが削除されることを意味するコード200が生成されます。詳細は、「APIレスポンス コードとエラー メッセージ」を参照してください。