Files
IIS 管理 API には、ファイル システムと直接対話するための一連のファイル API が用意されています。 つまり、API をローカルまたはリモートで使用して、ファイルが最新の場合は、コンテンツのデプロイ、編集、またはチェックを行うことができます。
/api/files エンドポイントは、マシン上のファイルとディレクトリのメタデータとコンテンツを公開します。 この API で使用できるファイルは、appsettings.jsonファイルの files 構成セクションで指定されているファイルに制限されます。 ディレクトリを指定せずに /api/files エンドポイントに対してクエリを実行すると、構成に存在する場所が一覧表示されます。 これらの場所は、API を介して使用できるすべてのファイル システム パスのルートを表します。 ファイル パスに操作を実行するために必要な要求がある限り、ファイルを作成、削除、および操作するには、標準の HTTP 投稿、削除、および修正プログラムの動詞を使用します。
ファイル
{
"name": "iisstart.png",
"id": "{id}",
"type": "file",
"physical_path": "C:\\inetpub\\wwwroot\\iisstart.png",
"exists": "true",
"size": "98757",
"created": "2017-01-09T18:08:33.5130112Z",
"last_modified": "2017-01-09T17:48:13.6180477Z",
"last_access": "2017-01-09T17:48:13.6180477Z",
"e_tag": "1d26aa08c67ed45",
"parent": {
"name": "wwwroot",
"id": "{id}",
"type": "directory",
"physical_path": "C:\\inetpub\\wwwroot"
},
"claims": [
"read",
"write"
]
}
ディレクトリ
{
"name": "wwwroot",
"id": "{id}",
"type": "directory",
"physical_path": "C:\\inetpub\\wwwroot",
"exists": "true",
"created": "2017-01-09T18:08:33.1380257Z",
"last_modified": "2017-01-30T17:01:15.2619212Z",
"last_access": "2017-01-30T17:01:15.2619212Z",
"total_files": "7",
"parent": {
"name": "inetpub",
"id": "a-nA1LZCBZ9jIqxr6e2uWg",
"type": "directory",
"physical_path": "C:\\inetpub"
},
"claims": [
"read",
"write"
]
}
/api/webserver/files エンドポイントは、IIS によって作成された仮想ファイル構造を公開します。 このエンドポイントの下にあるすべてのファイル リソースは、一部の Web サイトに属し、そのファイルのパスは、そのファイルが属する Web サイトに対する相対パスです。 これにより、Web サイトをファイル システム ルートとして扱うことができます。これは、Web サーバーのシナリオで望ましいものです。 仮想ディレクトリは、Web サイトの仮想ファイル階層を完全に表示するために、通常のディレクトリに含まれています。
すべての Web サーバー ファイルには、/api/files エンドポイントから取得できるファイル メタデータであるfile_infoへの参照があります。
Web ファイル
{
"name": "iisstart.png",
"id": "{id}",
"type": "file",
"path": "/iisstart.png",
"parent": {
"name": "",
"id": "{id}",
"type": "application",
"path": "/"
},
"website": {
"name": "Default Web Site",
"id": "{id}",
"status": "started"
},
"file_info": {
"name": "iisstart.png",
"id": "{id}",
"type": "file",
"physical_path": "C:\\inetpub\\wwwroot\\iisstart.png"
}
}
Web ディレクトリ
{
"name": "imgs",
"id": "{id}",
"type": "directory",
"path": "/imgs",
"parent": {
"name": "",
"id": "{id}",
"type": "application",
"path": "/"
},
"website": {
"name": "Default Web Site",
"id": "{id}",
"status": "started"
},
"file_info": {
"name": "imgs",
"id": "{id}",
"type": "directory",
"physical_path": "C:\\inetpub\\wwwroot\\imgs"
}
}
API では、 /api/files/copy エンドポイントと /api/files/ move エンドポイントを使用したファイルのコピーと 移動が サポートされています。 ファイルをコピーするプロセスは、目的のコピー操作を記述する POST 要求を API に実行することによって実行されます。
POST
{
"name":"{optional name of the destination file}",
"file": {
"id": "{id property of the file to copy}"
},
"parent": {
"id": "{id property of the directory to copy to}"
}
}
/api/files ルートの下のリソースには、ファイルのメタデータのみが含まれます。 ファイルのコンテンツを操作するには、 /api/files/content/{id} ルートを使用する必要があります。 このルートでは、 アプリケーション/オクテット ストリーム コンテンツ タイプを使用してデータを送信します。 ファイルのコンテンツ URL に対して GET 要求を実行すると、ファイルの生バイトが再処理されます。 この操作では HTTP 範囲要求がサポートされているため、ファイルをチャンクでダウンロードできます。 ファイルのコンテンツ URL に対して PUT 要求を実行すると、ファイルのコンテンツが要求本文に置き換えられます。 この操作では、ファイルのランダム アクセス操作を有効にする HTTP コンテンツ範囲要求がサポートされます。
ファイルの 2 番目の 500 バイトをダウンロードする
GET /api/files/content/{id}
Access-Token: Bearer {Access-Token}
Range: bytes=500-999
1000 バイト ファイルの 2 番目の 500 バイトを編集する
PUT /api/files/content/{id}
Access-Token: Bearer {Access-Token}
Content-Range: bytes 500-999/1000
Content-Length: 500
ファイルは、 API の /api/files/content エンドポイントを使用してダウンロードできます。 このエンドポイントの欠点は、 API ルートの下にあるため、アクセス トークンを必要とすることです。 つまり、ブラウザーを使用してファイルをダウンロードすることはできません。 /api/files/download エンドポイントを使用すると、一時的なダウンロード リンクを作成できます。 これらのダウンロード リンクは一意でランダムに生成され、アクセス トークンは必要ありません。 生成されたダウンロード リンクは 、/downloads/{random_sequence} の形式になります。 ダウンロード リンクを生成するときに、ダウンロード リンクを使用できる期間を指定する場合は、オプションの time-to-live (ttl) パラメーターを使用できます。 既定値は 5 秒です。
ダウンロードが生成されると、ダウンロードのリンクが HTTP 応答の Location ヘッダーに返されます。
POST
{
"file": {
"id": "{id of the file to download}"
},
"ttl": "10000"
}
files API を使用して、ファイル共有にあるファイルを管理できます。 この機能を有効にするには、ファイル共有で、API が実行されているマシンを表すプリンシパルに必要なファイル システムのアクセス許可を許可する必要があります。 たとえば、 \\share\images に共有コンテンツがあり、 web-prod-1 という名前の Web サーバーで実行されている API でこれらのファイルを列挙できるようにする必要があるとします。 これを許可するには、管理者が \\share\images ディレクトリの ACL を変更して 、Web-prod-1 Active Directory オブジェクトへの READ アクセスを許可する必要があります。 これが完了すると、 Web-prod-1 マシン上のサービスは、このディレクトリにアクセスし、ファイルを読み取り、API を介して公開できるようになります。
API のファイル システム アクセスは、 appsettings ファイルで指定されている一連のルート フォルダー (場所と呼ばれます) に制限されます。 これらの場所は、ファイル API の観点からはルートとして表示されますが、物理ドライブでは、入れ子になったフォルダー、ドライブのルート、さらにはネットワーク共有である可能性があります。 場所ごとに、読み取りと書き込みのアクセスは個別に制御されます。 場所に含まれていないファイル システム上のパスは、ファイル システム API には表示されません。
バージョン 2.2.0 以降では、 /api/files/locations エンドポイントを使用して場所の設定にアクセスできます。 このエンドポイントは、API の 所有者 ユーザー グループ内のユーザーにロックダウンされます。 つまり、場所エンドポイントにアクセスするには Windows 認証が必要です。 場所を追加または削除すると、API に対するファイル システム アクセスが追加または削除されます。 このエンドポイントでは、既存の場所を作成、編集、削除するための GET、PATCH、POST、DELETE がサポートされています。 場所の編集は物理ファイルに影響を及ぼすので、ファイル システムの API のビューのみを操作します。
既定の場所の構成
{
"locations": [
{
"alias": "inetpub",
"id": "{id}",
"path": "C:\\inetpub",
"claims": [
"read"
]
}
]
}