URLトランザクションとフォーマット

本セクションでは、SenseTalkを使用して、URL（Uniform Resource Locator）を介してインターネット上のリソースにアクセスする方法について説明します。 本メカニズムを使用すると、SenseTalkがインターネット上のファイルやウェブサイトの内容にアクセスしたり、標準プロトコルを使ってリモートサーバーと通信することが可能になります。

SenseTalkでは、標準URLフォーマットの情報を簡単に変換するのに利用できる関数を多数サポートしています。

スクリプト内におけるURLリソースの参照

URLを介してアクセスするファイルやその他のインターネットリソースをスクリプト内で参照するには、単語urlと、その後にファイルまたはリソースのURLとして評価される式を続けて使用します。

urlStringは、「file:」タイプ、「http:」タイプまたは「ftp:」タイプのURL となります。 「file:」タイプのURLは、コンテナとして処理できます。つまり、その中にコンテンツを格納したり、そのコンテンツを変更することが可能です（ファイルへの書き込みアクセスを有する場合）。 urlPropertyListを使用する場合は、「スキーム」や「ホスト」、「パス」、「クエリ」およびmakeURL()関数で定義されるその他のキーを含むことができます。

この構文を使用してインターネットからhttpリソースを取り出す場合は、http GET演算を使用します。 urlStringまたはurlPropertyListにより、クエリデータを組み込んでフォームの提出をシミュレートすることができます。 文字列を使用する場合は、makeURL()関数を使用すると、適切にフォーマットされたクエリを含む文字列を簡単に構成できます。

with headers headerPropertyListを指定する場合は、headerPropertyListは、そのURLへのアクセスに使用するカスタムHTTPヘッダーを含むプロパティリストである必要があります。 カスタムヘッダー情報は、GET（URLへのアクセス時）およびPOST（postコマンドの使用時）演算の標準ヘッダーと共に渡されます。

URLにアクセスしたら、スクリプトの次の行でresult()関数を呼び出すことにより、リモート演算のステータスをチェックできます。 本関数は、ステータス値が（the URLErrorLevelグローバルプロパティで指定される）エラーとして処理される最低レベル未満の場合はリクエストのステータス値を、 ステータスが本レベル以上でかつthrowExceptionResultsがfalseに設定されている場合は例外を返します。

URLから取り出されるデータは、the defaultStringEncodingグローバルプロパティの現在の設定に従って、テキストとして解釈されます。 URLデータをフェッチする前に、本プロパティを現在のエンコーディング（ほとんどの場合は「UTF8」）に設定します。

構文：

url urlString {with headers headerPropertyList}

url urlPropertyList {with headers headerPropertyList}

例：

put url "http://www.somewhere.com/somepage" into htmlContents

put htmlContents into url "file://localhost/localCopy"

例：

put (scheme:"http", host:"www.apple.com") into applePage

URLの挙動を構成する

SenseTalkには、ユーザーが使用できる複数のグローバルプロパティが存在し、これらはスクリプトからアクセスするURLの挙動に影響を及ぼします。

  • the URLCacheEnabled：URLリソースから取り出したコンテンツをキャッシュするかどうかを管理します。
  • the URLTimeout：URLリクエストトがタイムアウトになる前に許容可能な最長の時間を指定します。
  • the URLErrorLevel：URLのコンテンツをフェッチする際にエラーとして処理されるURLの最低のステータス値を設定します。

これらのグローバルプロパティについては、URLとソケットの扱いに関するグローバルプロパティで詳細に説明します。

インターネットおよびURLコマンドと関数

SenseTalkでは、インターネット上でトランザクションを実行したり、標準フォーマットのURLとデータを操作するための複数のコマンドと関数を利用できます。

postコマンドは、データをURLにポストし、その結果を取り出します。 makeURL()関数は、所定の構成要素から適切な形式のURL文字列を構成するのに役立てることができ、本関数のコンパニオン関数であるextractURL()関数は、URL文字列から構成要素を抽出します。 URLEncodeおよびURLDecode関数は、（通常URLクエリとネットワーク経由で渡されるデータで使用される）特別な符号化フォーマットと、テキストとの変換を行います。

postコマンド

挙動：postコマンドを使用すると、オンラインのウェブベースのサービスによるトランザクションを実行したり、ウェブ形式のポスティングやウェブサーバーとの同様のやり取りをシミュレートすることができます。 ウェブサーバーから返される結果は、変数itに格納されます。

dataは、任意のテキスト文字列か、プロパティリストとすることができ、後者の場合は標準クエリフォーマットで自動的にフォーマットされます。 postコマンドは、the URLTimeoutグローバルプロパティによって指定される最長時間を上限としてウェブサーバーから応答を受け取るまで待機し、その後スクリプトの次の行に進みます。 受け取る応答が何であれ、すべて変数itに格納されます。 割り当てられた時間内に応答を受け取らない場合や、その他のエラーが発生する場合は、変数itはemptyとなり、the resultはエラーを示す例外オブジェクトに設定されます。

構文：

post data to url theURL

例：

post queryData to url "http://someservice.net" with headers ("Content-Type": "text/xml")

例：

post URLEncode(dataToPost) to url makeURL(urlComponents)

put it into postResults

post multipartコマンド

挙動：マルチパートデータをサーバーにポストします。 contentToSendは、1つ以上のファイルのコンテンツなど、送信する単一のテキスト値または値のリストか、プロパティリストまたはプロパティリストのリストとすることができます。後者の場合は、データを転送するフォーマットに対してより厳密な制御を提供したり、コンテンツに関する追加情報を提供することができます。 「as data」を指定すると、ファイルコンテンツがbase64にエンコードされる結果となります。 ファイル名の使用はオプションですが、ファイルの送信時にはこの使用が推奨されます。

構文：

post multipart contentToSend to URL serverURL

例：

post multipart (filename:"/tmp/xyz", body:file "/tmp/xyz" as data) to URL serverURL

技術トピック

ポストしようとしているコンテンツに関する一連のルールは以下の通りです。

  • コンテンツの値がリストの場合は、リスト内の各アイテムはマルチパートコンテンツの個別のパートとして処理され、以下のルールが各パートに適用されます（個々のパートはリストではない場合があり、サブパートはサポートされません）。
  • コンテンツの値がバイナリデータ値（一般的に「as data」演算子の使用によって実現される）の場合は、ボディは自動的にbase64にエンコードされ、適切なContent-TypeとContent-Transfer-Encodingのヘッダー値が提供されます。
  • コンテンツの値がバイナリデータでもなく、プロパティリストでもない場合は、コンテンツの文字列値がボディとして使用され、「Content-Type: text/plain」ヘッダーが提供されます。
  • コンテンツ値がプロパティリストの場合は、ボディコンテンツとオプションのヘッダー情報の両方が提供されます。 以下のプロパティは特別な意味を持ちます。
    • Body：必須。 この値は、本ルールで説明されるように、データもしくはテキスト文字列値のいずれか、またはコンテンツ値のリスト（最上位レベルのみ）として、本パートのボディコンテンツとなります。
    • Header：追加のヘッダーフィールドを定義するプロパティリスト。 本プロパティは、ヘッダーの名前をコンテンツのプロパティリスト内のその他のキーと同じにする必要がある場合にのみ必要となります。 それ以外の場合は、ヘッダーのキー／値のペアをコンテンツのプロパティリストに直接組み込むことができます。
    • Disposition：「Content-Disposition」ヘッダーを構成するのに使用します。 適切な値は、「inline」や「attachment」などです。 本プロパティを指定しない場合は、「form-data」が使用されます。
    • FieldName：「Content-Disposition」ヘッダーを構成するのに使用します。 フォームフィールド名を指定しない場合は、「field1」や「field2」などの名前が自動的に生成されます。
    • FileName：「Content-Disposition」ヘッダーを構成するのに使用します。 本プロパティを指定する場合は、これがContent-Dispositionヘッダーの一部として組み込まれます。 ファイルのアップロード時は、 FileNameを指定することが推奨されます。

プロパティリストを（リスト内のパートとしてではなく）最上位レベルで使用する場合は、いくつかの特別なルールが適用されます。 本レベルにおいて、ボディはリストとすることができます。 また、以下の追加プロパティが認識されます。

  • MultipartBoundary：各パートを分けるのに使用するテキスト文字列（本プロパティを指定しない場合は、適切な文字列が自動的に生成されます）。 カスタムの「Content-Type」ヘッダーを最上位レベルで指定する場合は、本ヘッダーに境界文字列を組み込み、MultipartBoundaryをその値と同じ境界文字列と共に組み込む必要があります。
  • TopHeader：メッセージの最上位レベルで追加のヘッダーフィールドを定義するプロパティリスト。 または、URLの後でヘッダーheaderFieldを指定することにより、最上位レベルのヘッダーフィールドにポストするURLを指定することができます。 「MIME-Version」プロパティをTopHeader内で使用しない場合は、自動的に値「1.0」が使用されます。 「Content-Type」プロパティを使用しない場合は、MultipartBoundaryプロパティによって定義される「multipart/form-data」タイプのコンテンツと境界文字列を指定するプロパティが自動的に生成されます（または、何も指定しないプロパティが自動的に生成されます）。

特別な意味を持たない各パート内の追加のプロパティは、メッセージの該当箇所に関するヘッダーフィールドとして処理されます。 以下のヘッダーフィールドは、コンテンツプロパティリストかヘッダープロパティリストのどちらかに組み込まれていない場合に自動的に生成されます。

  • 「Content-Disposition」プロパティを含まない場合は、Disposition、FieldNameおよびFileNameに対して提供される値またはデフォルトを使用して（各プロパティについては上記の説明を参照）、Content-Dispositionヘッダーが自動的に生成されます。
  • 「Content-Type」プロパティを含まない場合は、Content-Typeヘッダーが自動的に生成されます。

multipartMIME関数

挙動：post multipartコマンドによって送られる、所定のコンテンツに関するBody情報とHeader情報を含むプロパティリストを生成します。 本関数は、問題の解決や、テキストとしてのHTTPメッセージの構築に役立てることができます。 本関数は、単一の値、値のリスト、またはプロパティリストもしくはプロパティリストのリストによって呼び出すことができます。 詳細情報は、post multipartコマンドを参照してください。

multipartMIME関数によって返される値はBodyプロパティを含むプロパティリストであり、そのBodyプロパティの値はmultipart-MIMEフォーマットで完全にフォーマットされた文字列となります。 Headerプロパティは、Bodyテキストに対応する適切なヘッダーを含むプロパティリストです。

例：

put (multipartMIME("Secret Message" as data) adding (request:"/")) as http

JSONFormat関数

挙動：任意のSenseTalk値に対して、JSONフォーマットのテキストを生成します。 JSONformat関数を使用してJSONフォーマットのテキストを生成し、これを別のプログラムで使用したり、JSONフォーマットを使用するウェブサービスやその他のプロセスにデータを送信したりするのに利用できます。 valueToFormatは、リストやプロパティリストなどの任意のSenseTalk値とすることができます。 リスト、プロパティリスト、テキストおよび数値（データや色など）以外の値は、テキストに変換されてからフォーマットされます。

構文：

JSONFormat(valueToFormat)

例：

put contentValue's JSONFormat into file outfile

JSONValue関数

挙動：JSONValue()関数を使用すると、JSONフォーマットのデータをSenseTalk値に変換して、スクリプト内で使用できるようになります。 JSONstringToEvaluateは、JSONフォーマットの文字列である必要があります。

構文：

JSONValue(JSONstringToEvaluate)

例：

put JSONValue(file "/tmp/myJSON.txt") into fileContents

makeURL関数

挙動：makeURL関数を使用すると、希望するURLの構成要素を含むプロパティリストを利用して、適切にフォーマットされたURL文字列を作成できます。 makeURL関数は、URLの各部分を必要に応じて自動的にエンコードします。 文字列の代わりにプロパティリストを含むURL式を使用する場合は、常に本関数が暗黙に呼び出されます。

構文：

makeURL(componentPropertyList)

the makeURL of componentPropertyList

例：

get makeURL(scheme:"http", host:"myserver.net", path:"slinky")

例：

put url makeURL(host:"google.com", path:"search", query:("q":"EggPlant", "ie":"UTF-8") ) into searchResults

componentPropertyListは、結果のURL文字列を構成するのに使用する構成要素を含むプロパティリストである必要があります。 以下の任意のプロパティを指定でき、その他のプロパティは無視されます。

scheme

「http」や「ftp」、「file」などのスキームまたはプロトコル（指定しない場合はhttpが使用されます）

host

URLが参照するホストマシン（ウェブサーバー）

path

ホストウェブサーバー上のリソースのパス

port

接続するポートの番号

user

サーバー上でログインするユーザーの名前（ftp URL向けに使用される場合もあります）

password

サーバー上でログインするのに使用されるパスワード（一部のftp URL向けにuserと併せて使用されます）

parameters

使用する追加パラメータ（ftp URL向けの「type」パラメータなど）

fragment

リソース内の特定の基準点を特定するフラグメント

query

ウェブサーバーに渡されるキーや値を含むプロパティリスト（ウェブページ上のフォームなどによって提供される）

関連：

extractURL関数

extractURL関数を使用すると、URL文字列をその構成要素を含むプロパティリストに簡単に分割できます。 extractURL関数は、URLの各部分を必要に応じて自動的にデコードします。

構文：

extractURL(urlString)

the extractURL of urlString

例：

put extractURL("http://myserver.net/slinky") into urlParts

urlStringは、標準URLフォーマットの文字列として評価される式である必要があります。 extractURL関数によって返される値は、そのURL文字列から抽出された構成要素の各部分を含むプロパティリストとなります。 urlStringがemptyの場合は、返されるプロパティリストもemptyとなり、それ以外の場合はURL文字列に組み込まれているものに応じて、以下の1つ以上のキーが組み込まれます。

scheme

「http」や「ftp」、「file」などのスキームまたはプロトコル

host

URLが参照するホストマシン（ウェブサーバー）

path

ホストウェブサーバー上のリソースのパス

port

接続するポートの番号

user

サーバー上でログインするユーザーの名前（ftp URL向けに使用される場合もあります）

password

サーバー上でログインするのに使用されるパスワード（一部のftp URL向けにuserと併せて使用されます）

parameters

使用する追加パラメータ（ftp URL向けの「type」パラメータなど）

fragment

リソース内の特定の基準点を特定するフラグメント

query

本キーの値は、ウェブサーバーに渡されるurlString内に存在するキーや値（ウェブページ上のフォームなどによって提供される）を含むプロパティリストとなります

関連：

URLEncode関数

挙動：URLEncode関数は、文字列内の各スペースを「+」記号で置き換え、スペース以外の英数字でない文字を3文字のコード「%xx」（xxはURL文字列で使用される置換済みの文字のASCII値を表す2桁の16進数）で置き換えます。 パラメータがプロパティリストの場合は、クエリがmakeURL()関数によってエンコードされるのと同じ方法で、URLクエリの文字列としてエンコードされます。 URLEncode関数を使用すると、インターネットリソースの取得に使用するURL文字列の一部としてデータを渡すのに適した方法で、文字列をエンコードできます。

構文：

URLEncode(文字列)

the URLEncode of 文字列

例：

put urlEncode(myData) into encodedData

関連：

URLDecode関数

挙動：URLDecode関数は、「%xx」（xxは2桁の16進数）形式のencodedStringからの各トリプレットを、そのASCII値を備えた文字で置き換えます。 encodedString内の「+」記号は、単一のスペース文字で置き換えられます。 URL文字列のデータをデコードする場合は、URLDecode関数を使用します。 これはurlEncode関数とは逆の操作となります。

構文：

URLDecode(encodedString)

the URLDecode of encodedString

例：

put urlDecode(encodedData) into myData

関連：

XMLRPCFormat()関数

挙動：任意のSenseTalk値に対して、XML-RPCフォーマットのテキストを生成します。 本関数は、XML-RPCメッセージのボディ内で使用するのに必要なフォーマットで、任意の値を表す文字列を返します。 XMLRPCFormat()関数を使用するとXML-RPCフォーマットのテキストを生成でき、これを別のプログラムで使用したり、XML-RPCフォーマットを使用するウェブサービスやその他のプロセスにデータを送信したりできるようになります。

valueToFormatは、リストやプロパティリスト、テキスト、数値、日付、バイナリデータなど、任意のSenseTalk値とすることができます。 その他の値は、フォーマット前にテキストに変換されます。

構文：

XMLRPCFormat(valueToFormat)

例：

put contentValue's XMLRPCFormat into file dataFile

XMLRPCValue()関数

挙動：XMLRPCValue()を使用してXML-RPCフォーマットのデータをSenseTalk値に変換し、スクリプト内で使用できます。 XMLRPCstringToEvaluateは、XML-RPCでフォーマットされた文字列である必要があります。

構文：

XMLRPCValue(XMLRPCstringToEvaluate)

例：

put XMLRPCValue(file "/tmp/myXMLRPC.txt") into dataReceived

 

This topic was last updated on 2月 01, 2019, at 11:13:23 午前.

Eggplant icon Eggplant.io | Documentation Home | User Forums | Support | Copyright © 2019 Eggplant