ZIA APIについて

API開発者およびリファレンスガイド
- リファレンスガイド
  - APIレート制限の概要
- APIの操作

APIを使用したSD-WAN統合

本記事では、以下の方法についてのみ記載しています。

ソフトウェア定義型広域ネットワーク(SD-WAN)のパートナーAPIキーへのアクセスを有効にする。
SD-WANパートナーがIPSec VPNトンネルに使用するのに最適な仮想IPアドレス(VIP)を決定する。
ロケーションおよびVPN認証情報APIリソースを使用して、IPSecVPNトンネルをセットアップします。

各パートナー(Riverbed SteelConnect、HPE Arubaなど)の詳細およびSD-WAN展開構成ガイドについては、SD-WANパートナーサイトを参照するか、Zscaler Business Developmentにお問い合わせください。

送信元IPアドレスに基づいて、ZIA管理ポータルへの制限付きアクセスを有効にしている場合は、API経由でZIA管理ポータルにアクセスするための許可リストに、SD-WANデバイスのIPアドレスを含める必要があります。詳細は、管理者用制限付きアクセスの設定を参照してください。

SD-WANのAPIアクセスをパートナーに提供する

SD-WANパートナーのAPIキーにより、テクノロジーパートナーはクラウドサービスAPI内のロケーションリソースとVPN資格情報リソースにアクセスできます。

SD-WANパートナーのAPIアクセスを有効にするには、次のように操作します。

ZIA管理ポータルにログインします。
SD-WANパートナーアクセスを有効にした状態で、SD-WANパートナーAPIロール]を構成します。
SD-WANパートナーのSD-WANパートナーAPIクライアントを構成し、適切なSD-WANパートナーAPIロールが適用されていることを確認します。
SD-WANパートナーAPIクライアントとロールが適切に構成されたら、パートナーキーを追加します。
[管理]>[クラウドサービスAPIキーの管理]で構成したクラウドサービスAPIキーを使用して、SD-WANパートナーのアクセスを有効にすることはできません。SD-WANパートナーのキーは、[管理]>[パートナー統合]で作成する必要があります。また、組織はSD-WANパートナーごとに1つのキーしか設定できません。
D-WANパートナーAPIクライアント資格情報とパートナーキーをSD-WANパートナーに送信します。

パートナーキーを編集、再生成、または削除した場合、SD-WANパートナーに変更を通知していることを確認してください。

SD-WAN統合用のZscalerデータセンターVIPの決定

SD-WANパートナーがIPSec VPNトンネルを確立するために、最適なプライマリーおよびセカンダリーデータセンターのVIPを選択する必要があります。クラウドに最適なVIPを決定するには、以下の方法のいずれかを使用します。

方法1 (推奨): GET /vips APIエンドポイントを使用して、クラウドの全VIPのフラットリストを取得します。Zscalerでは、IPSec VPNトンネルに最適なVIPを決定するために独自のインテリジェンスを追加したい場合、またはユーザーが選択をオーバーライドできるようにするために完全なリストを提供したい場合、リクエストにすべてのVIPを含めることをお勧めします。たとえば、Pythonでは、すべてのVIPを含めるためのGETリクエストは以下のようになります。
```
conn.request("GET", "/api/v1/vips?include=all", headers=headers)
```
GET /vipsの詳細については、APIリファレンスのトラフィック転送を参照してください。
方法2: GET https://pac.<Zscalerクラウド>.net/getVpnEndpointsAPIエンドポイントを使用します。ここで、<Zscalerクラウド>は、Zscalerによって組織にプロビジョニングされたクラウド名です(例：zscalerbeta)。このエンドポイントは、エッジデバイスの送信元IPまたは位置座標へのジオロケーションの近接性に基づいて、プライマリー、セカンダリーおよびターシャリーVIPを返します。詳細は、ZIAのクラウド名とはを参照してください。
- HTTPリクエストが発せられた送信元IP (例：https://pac.zscalerbeta.net/getVpnEndpoints)に基づいてVIPを取得するには、属性なしのgetVpnEndpointsを使用します。
- getVpnEndpoints?srcIp=<送信先IPアドレス>クエリーパラメーターを使用して、特定の送信元IPに基づいてVIPを取得します(例：https://pac.zscalerbeta.net/getVpnEndpoints?srcIp=194.208.68.97)。
- getVpnEndpoints?lat=<緯度座標>&long=<経度座標>クエリーパラメーターを使用して、位置座標に基づいてVIPを取得します(例：https://pac.zscalerbeta.net/getVpnEndpoints?lat=47.1275&long=10.2637)。
- getVpnEndpoints?subcloud=<サブクラウド>クエリーパラメーターを使用して、特定のサブクラウドに基づいてVIPを取得します。詳細は、サブクラウドについての理解を参照してください(例：https://pac.zscalerbeta.net/getVpnEndpoints?subcloud=americas)。
- subcloudクエリーパラメーターは、エンドポイントの他のパラメーター(https://pac.zscalerbeta.net/getVpnEndpoints?lat=47.1275&long=10.2637&subcloud=americas)と共に使用できます。
- getVpnEndpoints?domesticPerf=<true/false>クエリーパラメーターを使用して、国内の国に基づき、VIPを取得します。デフォルトはfalseです。trueに設定すると、要求元のユーザーの国内にある最も近い3つのエンドポイントが利用可能な場合は、レスポンスに表示されます(例：https://pac.zscalerbeta.net/getVpnEndpoints?domesticPref=true)。
  domesticPrefクエリーパラメーターは、エンドポイントの送信元IP (srcIP)および位置座標(lat/long)パラメーターと共に使用できます(例：https://pac.zscalerbeta.net/getVpnEndpoints?srcIp=194.208.68.97&lat=47.1275&long=10.2637&domesticPref=true)。
API呼び出しに成功すると、200 OKのステータスコードが返されます。ただし、無効なクエリパラメータが指定された場合は、400のステータスコードが返されます。詳細については、API応答コードとエラーメッセージを参照してください。
getVpnEndpoints APIエンドポイントには、整数値のみを渡す必要があります。
APIコールに成功すると、例えば以下のようなVIP情報がレスポンス内で返されます。例えば：
```
{
    "primaryIp": "165.225.72.39",
    "primaryMeta": {
        "region": "Europe",
        "country": "Germany",
        "city": "Frankfurt",
        "dcName": "FRA4",
        "latitude": 50.000000,
        "longitude": 9.000000
    },
    "secondaryIp": "104.129.194.39",
"secondaryMeta": {
        "region": "NorthAmerica",
        "country": "United States",
        "city": "Washington, DC",
        "dcName": "WAS1",
        "latitude": 39.000000,
        "longitude": -77.000000
    },
    "tertiaryIp": "199.168.148.132",
"tertiaryMeta": {
        "region": "NorthAmerica",
        "country": "United States",
        "city": "Fremont, CA",
        "dcName": "FMT1",
        "latitude": 37.000000,
        "longitude": -121.000000
    }
}
```
方法3 (非推奨):クラウドのZscalerデータセンターVIP JSONを参照し、組織のロケーションに最も近い2つのデータセンターを見つけます。詳細は、ZIA パブリックサービスエッジのホスト名とIPアドレスの検索を参照してください。

VIPを決定したら、この情報をSD-WANパートナーに提供するようにしてください。

SD-WAN統合のためのロケーションとVPN資格情報APIリソースを使用する

ZIA管理ポータル内で、設定したロケーションまたはVPN資格情報を確認し、[管理担当者]フィールドを設定して、それらを管理する適切なSD-WANパートナーを割り当てます。パートナーがGET /locationsを使用してロケーションの詳細を取得するには、[管理担当者]フィールド(すなわち、managedBy属性)を、当社サービスで定義されているパートナー(Riverbed SteelConnect、HPE Arubaなど)のいずれかに設定する必要があります。詳細については、managedBy属性についてセクションを参照してください。

ロケーションリソース、およびPOST /vpnCredentialsリソースは、SD-WANパートナー統合ワークフローをサポートするために設計されています。したがって、パートナー固有のものではないワークフローにそれらを使用しようとする場合、いくつかの制限が適用されます。また、ZIA管理ポータル内のすべてのロケーションの特徴と機能は、APIを介して利用できません(サブロケーション、パブリックIPアドレス、プロキシーポート、ロケーショングループなど)。

managedBy属性の説明

managedBy属性は、エンティティーを表す一意の識別子です。この場合、ロケーションまたはVPN資格情報を管理するエンティティーです。ZIA管理ポータルでは、これは[ロケーション]および[VPN資格情報]ページ内の[管理担当者]フィールドで表され、自分またはパートナー(例：Riverbed SteelConnect)に設定することができます。画像を参照してください。

閉じる

ロケーションとVPN資格情報のリソースについては、APIはオブジェクトモデルにmanagedBy属性を含んでいます。ロケーションとVPN資格情報のリソースは、適切なエンティティによって管理されているオブジェクトのみを返します。そのため、managedBy属性は、当サービスで名付けられた以下のパートナーのいずれかに設定されている必要があります。

シスコ・ビプテラ
シトリックスSD-WAN
クラウドジェニックス
HPE Aruba
ネゲナ
リバーベッドSteelConnect
シルバーピーク
VMware VeloCloud

たとえば、パートナーがRiverbed SteelConnectで、GETアクションを実行するための呼び出しを行った場合、そのパートナーはRiverbed SteelConnectでタグ付けされたロケーションとVPN認証情報オブジェクトのみを応答で取得できます。彼らはあなたが管理しているオブジェクト(つまりSelf)を取得することはできません。また、パートナーがPOST、PUTまたはDELETEアクションを実行するために呼び出しを行った場合、managedBy属性は自動的にパートナーに割り当てられます。

SD-WANパートナーキーを使用してAPI呼び出しを行う場合、ペイロードにmanagedBy属性に一致するパートナー名が含まれていないと、呼び出しに失敗します。

ロケーション一覧を取得する

ロケーションリソースにより、SD-WANパートナーはZscalerサービス定義のロケーションの全属性をリクエストとしてエクスポートすることができます。そのため、パートナーの場合、GET /locationsを呼び出すと、パートナーが管理するロケーションオブジェクトのリストを取得することができます。例えば、Pythonでは、Riverbed SteelConnectパートナーによるGETリクエストは次のように表示されます。

conn.request("GET", "/api/v1/locations", headers=headers)

レスポンスは次のようになります。

[
    {
        "name": "nyc-2",
        "id": 4562809,
        "managedBy": {
            "id": 1,
            "name": "Riverbed SteelConnect"
        },
        "vpnCredentials": [
            {
                "id": 4562807,
                "type": "UFQDN",
                "fqdn": "nyc-1-37@yourcompany.com",
                "comments": "created automatically"
            }
        ]
    },
    {
        "name": "sjc-1",
        "id": 4562808,
        "managedBy": {
            "id": 1,
            "name": "Riverbed SteelConnect"
        },
        "vpnCredentials": [
            {
                "id": 4562805,
                "type": "UFQDN",
                "fqdn": "sjc-1-37@yourcompany.com",
                "comments": "created automatically"
            }
        ]
    }
]

使用する場合、Zscalerでは、pageSizeクエリーパラメーターを100以上に変更するか、pageクエリーパラメーターを使用してすべての結果を反復し、最後のページの結果が100未満になるまで繰り返すことをお勧めします。

/locationsにGETリクエストを送信した場合、セキュリティ上の理由から、関連するVPN資格情報の事前共有キー(PSK)はレスポンスに含まれません。

詳細については、managedBy 属性について ]セクションを参照してください。

ロケーションの追加、更新、削除

SD-WANパートナーは、お客様が管理しているオブジェクト(Selfなど)を取得することはできません。パートナーがロケーションに対してPOST、PUT、またはDELETEアクションを実行する呼び出しを行った場合、パートナーが管理しているロケーションに対してのみ実行できます。詳細については、[ managedBy 属性について ]セクションを参照してください。

/locations/{locationId}にPUTリクエストを送っても、ロケーションの完全修飾ドメイン名(fqdn)を更新することはできません。fqdnがリクエストの中で変更された場合、その変更は無視されます。

VPN資格情報の追加

POST /vpnCredentialsリソースを使用すると、SD-WANパートナーはIPSec VPN認証を設定できます。詳細については、VPN認証情報の追加を参照してください。