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

このセクションでは、SenseTalkを使用して、そのURLを通じてインターネット上のリソースにアクセスする方法について説明します。このメカニズムを通じて、SenseTalkはインターネット全体のファイルやウェブサイトの内容にアクセスし、標準プロトコルを使用してリモートサーバーと通信することができます。

標準的なURLフォーマット間で情報を変換するために使いやすいいくつかのサポート関数が用意されています。

スクリプト内でURLリソースを参照する

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

urlString は“file:”、“http:”、または“ftp:”タイプのURLである可能性があります。 “file:”タイプのURLはコンテナとして扱うことができます - ファイルへの書き込みアクセスがある場合、その内容を保存したり変更したりすることができます。 urlPropertyList を使用する場合、それは makeURL() 関数によって定義される“scheme”、“host”、“path”、“query”などのキーを含むことができます。

この構文を使用してインターネットからhttpリソースを取得するとき、http GET操作が使用されます。 urlString または urlPropertyList には、フォームを提出することをシミュレートするためのクエリデータを含めることができます。文字列を使用する場合、makeURL() 関数を使用して正しくフォーマットされたクエリを含む文字列を簡単に構築することができます。

with headers headerPropertyList が指定されている場合、headerPropertyList はそのURLにアクセスする際に使用するカスタムHTTPヘッダーを含むプロパティリストであるべきです。カスタムヘッダー情報は、GET（URLにアクセスするとき）とPOST（post コマンドを使用するとき）の両方の操作に対して任意の標準ヘッダーと一緒に渡されます。

URLにアクセスした後、スクリプトの次の行で result() 関数を呼び出すことで、リモート操作のステータスを確認することができます。これは、リクエストのステータス値がエラーとして扱われる最小レベル（the URLErrorLevel グローバルプロパティによって指定された）未満の場合、またはステータスがそのレベルまたはそれ以上であり、the throwExceptionResults がfalseに設定されている場合、例外を返します。

URLから取得したデータは、the defaultStringEncoding グローバルプロパティの現在の設定に従ってテキストとして解釈されます。URLデータを取得する前に、このプロパティを正しいエンコーディング（通常は "UTF8"）に設定します。

構文:
url urlString {with headers headerPropertyList}
url urlPropertyList {with headers headerPropertyList}

例:

url "http://www.somewhere.com/somepage" を htmlContents に put
htmlContents を url "file://localhost/localCopy" に put

例:

{scheme:"http", host:"www.apple.com"} を applePage に put

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コマンドを使用して、オンラインのWebベースのサービスとのトランザクションを行ったり、Webフォームの投稿をシミュレートしたり、Webサーバーとの類似のやり取りを行います。Webサーバーが返す結果は、変数itに格納されます。

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

構文:
post data to url theURL

例:

queryDataをurl "http://someservice.net"にpostする、ヘッダーは{"Content-Type": "text/xml"}

例:

URLEncode(dataToPost)をurl makeURL(urlComponents)にpostする
postResultsにそれを入れる

Post Multipart コマンド

動作: サーバーにマルチパートデータを投稿します。 contentToSend は、単一のテキスト値またはファイルの内容を含む値のリスト、またはデータが送信される形式に対してより多くの制御を提供したり、内容に関する追加情報を提供するためのプロパティリストまたはプロパティリストのリストです。 "as data" を指定すると、ファイルの内容がBase64でエンコードされます。ファイル名を含めることは任意ですが、ファイルを送信する場合は推奨されます。

md 構文：
post multipart contentToSend to URL serverURL

例:

multipart {filename:"/tmp/xyz", body:file "/tmp/xyz" as data}をURL serverURLにpostする

Tech Talk

投稿されるコンテンツの全体的なルールは次のとおりです:

• コンテンツの値がリストである場合、リスト内の各アイテムはマルチパートコンテンツの別々のパートとして扱われ、以下のルールが各パートに適用されます（個々のパートはリストであってはならず、サブパートはサポートされていません）。
• コンテンツの値がバイナリデータ値（通常は"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を含めることを推奨します。

プロパティリストがトップレベルで使用される場合（リスト内のパートとしてではない場合）、特別なルールが適用されます。このレベルのBodyはリストにすることができます。また、以下の追加のプロパティが認識されます：

• MultipartBoundary: パートを区切るために使用されるテキスト文字列（指定されていない場合、適切な文字列が自動的に生成されます）。カスタムの"Content-Type"ヘッダーがトップレベルで供給される場合、それは境界文字列を含むべきであり、MultipartBoundaryはその境界文字列をその値として含める必要があります。
• TopHeader: メッセージのトップレベルで追加のヘッダーフィールドを定義するプロパティリスト。または、URLに投稿する際にheaders headerFieldsを指定で指定することで、トップレベルのヘッダーフィールドを提供することができます。"MIME-Version"プロパティがTopHeaderに指定されていない場合、自動的に"1.0"の値が含まれます。"Content-Type"プロパティが含まれていない場合、"multipart/form-data"のコンテンツタイプと、MultipartBoundaryプロパティによって定義される境界文字列（または指定されていない場合は自動的に生成される）を指定するものが自動的に生成されます。

メッセージのそのパートのヘッダーフィールドとして扱われる特別な意味を持たない各パートの追加のプロパティがあります。以下のヘッダーフィールドは、それらがコンテンツプロパティリストまたはそのHeaderプロパティリストに含まれていない場合、自動的に生成されます：

• "Content-Disposition"プロパティが含まれていない場合、Disposition、FieldName、およびFileNameまたはそれらのデフォルトの値を使用して、Content-Dispositionヘッダーが自動的に生成されます。これらのプロパティについては、上記を参照してください。
• "Content-Type"プロパティが含まれていない場合、Content-Typeヘッダーが自動的に生成されます。

MultipartMIME 関数

動作: post multipartコマンドで送信されるように、指定されたコンテンツのBodyとHeader情報を含むプロパティリストを生成します。これは問題のトラブルシューティングやHTTPメッセージをテキストとして構築するために役立ちます。この関数は、単一の値、値のリスト、またはプロパティリストまたはプロパティリストのリストで呼び出すことができます。詳細については、Post Multipart コマンドを参照してください。

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

例:

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

JSONFormat 関数

動作： 任意のSenseTalk値のためのJSON形式のテキストを生成します。JSONformat関数を使用して、他のプログラムで使用するためのJSON形式のテキストを生成したり、ウェブサービスや他のJSON形式を使用するプロセスにデータを送信するために使用します。_valueToFormat_は、リストやプロパティリストを含む任意のSenseTalk値であることができます。リスト、プロパティリスト、テキスト、数字以外の値（例えば、日付や色）は、フォーマットする前にテキストに変換されます。

大部分の場合、SenseTalkの値は自動的にフォーマットされた出力内の対応するタイプにマッピングされます。SenseTalkリストはJSONリストになり、SenseTalkプロパティリストはJSONオブジェクトになります。ただし、時々、個々の要素について「数値として」、「文字列として」（または「テキストとして」）、または「ブール値として」を指定する必要があるかもしれません。これは、SenseTalkが通常、文字列と数値の値を区別しないためです - それは単にコンテクストや操作に応じて値を必要に応じて変換します。しかし、JSONとしてフォーマットする場合、SenseTalkは文字列が必要か数値が必要かを知る方法がありません。

構文:
JSONFormat( valueToFormat )
{the} JSONFormat of valueToFormat

例:

put contentValue's JSONFormat into file outfile

例:

この例では、JSONFormat関数を使用して、リストされている値を持つJSON文字列を返すSenseTalk呼び出しを示しています：

set listOfValues to ["a",Yes,"0500",22]
put JSONFormat(listOfValues)

上記の例からのJSON出力は以下のようになります：

["a",true,"0500",22]

"はい"をテキストとして、0500を数値として、22を文字列として持つためには、このようにコードで指定することができます：

set listOfValues to ["a", Yes as text, "0500" as a number, 22 as a string]
put JSONFormat(listOfValues)

上記からの出力は現在このようになっています：

["a","Yes",500,"22"]

JSONValue 関数

動作： JSONValue関数を使用して、JSON形式のデータをスクリプト内で使用するためのSenseTalk値に変換します。

構文:
JSONValue( JSONstringToEvaluate )
{the} JSONValue of JSONstringToEvaluate

_JSONstringToEvaluate_は、JSON形式の文字列でなければなりません。

例:

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

例:

この例では、システム上のJSONファイルには、アメリカのコロラド州デンバーに関する情報が含まれています：

{
"city" : "Denver",
"airports" : ["Denver International", "Rocky Mountain Metropolitan", "Centennial", "Front Range"],
"elevation" : 5280,
"coordinates" : [39.7392, 104.9903],
"locatedInMountains" : false,
"stateCapital" : true
}

次のSenseTalkは、JSONValue関数を使用して、JSONファイルの内容にアクセスします：

put file "/Users/elizabethsimons/Desktop/DenverInfo.json" into fileContents
put JSONValue(fileContents) into DenverInfo
put DenverInfo

上記が実行されると、出力は次のようになります：

{airports:["Denver International","Rocky Mountain Metropolitan","Centennial","Front Range"], city:"Denver", coordinates:[39.7392,104.9903], elevation:5280, locatedInMountains:"False", stateCapital:"True"}

MakeURL 関数

動作： makeURL関数を使用して、希望するURLの構成要素を含むプロパティリストを使用して、正しくフォーマットされたURL文字列を作成します。 makeURL関数は、文字列の代わりにプロパティリストを含む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ではユーザーと一緒に使用されます）
parameters	含める追加のパラメーター（ftp URLの“type”パラメーターなど）
fragment	フラグメントはリソース内の特定のアンカーポイントを識別します
query	ウェブページのフォームによって供給されるような、ウェブサーバーに渡されるキーと値を含むプロパティリスト

関連項目:

• [*関連項目 ExtractURL 関数](#extract-url)
• URLEncode 関数

ExtractURL 関数

_urlString_は、標準のURL形式の文字列を評価する表現であるべきです。extractURL関数によって返される値は、そのURL文字列から抽出されたコンポーネント部分を含むプロパティリストになります。_urlString_が空である場合、返されるプロパティリストは空になります。それ以外の場合、URL文字列に含まれていた内容に応じて、以下のキーの一つ以上を含むことになります：

構文:
extractURL( urlString )
{the} extractURL of urlString

例:

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

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

scheme	スキームまたはプロトコル、たとえば“http”、“ftp”、または“file”
host	URLが参照するホストマシン（ウェブサーバー）
path	ホストウェブサーバー上のリソースへのパス
port	接続するポート番号
user
password
parameters
fragment	フラグメントはリソース内の特定のアンカーポイントを識別します
query

関連項目:

• MakeURL関数

URLEncode 関数

動作： URLEncode関数は、文字列中の各スペースを '+' 文字に置き換え、スペース以外の非英数字文字を形式'%xx'の3文字のコードに置き換えます。ここで、xxは、URL文字列で使用される置換文字のASCII値を表す2桁の16進数です。パラメータがプロパティリストの場合、makeURL関数でクエリがエンコードされるのと同様に、URLクエリ文字列としてエンコードされます。URL文字列の一部としてデータを渡すために適した形式で文字列をエンコードするためにURLEncode関数を使用します。

構文：
URLEncode( string )
{the} URLEncode of string

例:

put urlEncode(myData) into encodedData

関連項目:

• URLDecode関数
• MakeURL関数

URLDecode 関数

動作： URLDecode関数は、encodedStringの'%xx'（xxは2桁の16進数）形式の各トリプレットを、そのASCII値を持つ文字に置き換えます。encodedString中の各'+'文字は単一のスペース文字に置き換えられます。URL文字列からデータをデコードするためにURLDecode関数を使用します。これはurlEncode関数の逆です。

構文：
URLDecode( encodedString )
{the} URLDecode of encodedString

例:

put urlDecode(encodedData) into myData

関連項目：

• URLencode関数

XMLRPCFormat 関数

動作： 任意のSenseTalk値に対してXML-RPCフォーマットのテキストを生成します。XML-RPCメッセージの本文内で使用する必要があるフォーマットで任意の値を表す文字列を返します。他のプログラムとの使用、またはXML-RPCフォーマットを使用するウェブサービスや他のプロセスにデータを送信するためにXMLRPCFormat関数を使用します。

大部分の場合、SenseTalkの値は自動的にフォーマットされた出力内の対応する型にマッピングされます。SenseTalkリストはXML-RPC配列に、SenseTalkプロパティリストはXML-RPC構造体になります。ただし、時々、特定の要素に対して「数値として」「文字列として（または"テキストとして"）」「整数として」「数値として」または「ブール値として」を指定する必要があります。これにより、期待される結果が得られます。これは、SenseTalkが通常は文字列と数値の値の間で区別をしないためです。それは単にコンテキストや操作に応じて値を変換します。

構文：
XMLRPCFormat( valueToFormat )
{the} XMLRPCFormat of valueToFormat

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

例:

put contentValue's XMLRPCFormat into file dataFile

例:

この例では、XMLRPCFormat関数を使用したSenseTalkの呼び出しを示しており、リストにある値でXML-RPCの文字列を返します：

set listOfValues to ["a",Yes,"0500",22]
put XMLRPCFormat(listOfValues)

上記の例の出力は以下のようになります：

<value><array><data>

<value><string>a</string></value>

<value><boolean>1</boolean></value>

<value><string>0500</string></value>

<value><int>22</int></value>

</data></array></value>

"Yes"をテキストとして、0500を整数として、22を数値として扱うためには、コードでそれを指定することができます：

set listOfValues to ["a", Yes as text, "0500" as integer, 22 as a number]
put XMLRPCFormat(listOfValues)

上記の出力は、今では次のようになります：

<value><array><data>

<value><string>a</string></value>

<value><string>Yes</string></value>

<value><int>500</int></value>

<value><double>22</double></value>

</data></array></value>

XMLRPCValue 関数

振る舞い: XML-RPCフォーマットのデータをスクリプト内で使用するためのSenseTalk値に変換するために、XMLRPCValue関数を使用します。XMLRPCstringToEvaluateは、XML-RPCフォーマットの文字列でなければなりません。

構文:
XMLRPCValue( XMLRPCstringToEvaluate )
{the} XMLRPCValue of XMLRPCstringToEvaluate

例:

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