3. cXML の基本

 このセクションでは、cXML の基本プロトコルとデータフォーマットについて説明します。この章には、すべてのトランザクションの実装に必要な情報が記載されています。

3.1 プロトコルの仕様

3.1.1 Request/Response モデル
3.1.2 cXML 変換
3.1.3 cXML ドキュメント
3.1.4 ラッピングレイヤ
3.1.5 添付ファイル
3.1.6 cXML エンベロープ
3.1.6.1 xml:lang で指定する地域情報
3.1.6.2 日付、時刻およびその他のデータタイプ
3.1.6.3 特殊文字
3.1.6.3.1 ドキュメントにおける特殊文字の処理
3.1.7 Header
3.1.7.1 From
3.1.7.2 To
3.1.7.3 Sender
3.1.7.4 UserAgent
3.1.7.5 Credential
3.1.7.6 Correspondent
3.1.8 Request
3.1.9 Response
3.1.9.1 Status
3.1.10 One-Way (非同期式) モデル
3.1.11 Message
3.1.12 転送オプション
3.1.13 サービス状況応答

3.2 基本要素

3.2.1 Type エンティティ
3.2.2 ベース要素

3.1 プロトコルの仕様

 cXML トランザクションには、Request/Response モデルと One-Way モデルの 2 つの通信モデルがあります。これら 2つのモデルは操作が厳密に定義されているため、実装は容易に行えます。状況によっては 1 つのモデルで対応できない場合があるため、両方のモデルが必要となります。

3.1.1 Request/Response モデル

 Request/Response トランザクションは、HTTP または HTTPS 接続でのみ実行できます。以下の図は、組織 A と B の間における Request/Response トランザクションの対話の手順を示しています。

図 1: Request/Response トランザクション

このトランザクションは、以下の手順で処理されます。

  1. サイト A は、サイト B のアドレスとして指定されている URL を参照して、サイト B との HTTP/1.x 接続を開始します。
  2. サイト A は、POST 操作を行い、cXML ドキュメントを HTTP 接続経由で送信します。その後サイト A は、Response 待ちとなります。
  3. サイト B の HTTP/1.x 準拠のサーバーは、手順 1 で参照された URL が示すリソースに HTTP Request を送信します。このリソースは、CGI プログラムや ASP ページなどで、サイト B の HTTP サーバーが認識できる有効なネットワーク所在地に存在する必要があります。
  4. 手順 3 で識別されたサイト B のリソースは、cXML ドキュメントの内容を読み取り、その Request を適切なハンドラにマッピングします。
  5. cXML Request に対応するサイト B のハンドラは、その Request に従って処理を行い、cXML Response ドキュメントを生成します。
  6. サイト B は、手順 1 で確立した HTTP 接続により、cXML Response をサイト A に送信します。
  7. サイト A は、cXML Response を読み取り、Request を発信したプロセスにその Request を返します。
  8. サイト A は、手順 1 で確立した HTTP 接続を切断します。

さらに Request/Response サイクルを続行する場合は、このプロセスが繰り返されます。上記手順の作業を単純化するために、cXML ドキュメントは次の 2 つの部分に分割されます。

  • Header – アドレス指定と認証情報で構成されます。
  • Request または Response データ – 特定の要求または応答、およびやり取りされる情報が含まれます。

これらの要素 (element) の両方とも、親エンベロープ要素に入れて転送されます。次の例は、cXML Request ドキュメントの構造を示しています。

次の例は、cXML Response ドキュメントの構造を示しています。

Response 構造では、Header 要素が使用されません。Response は常に Request と同じ HTTP 接続で送信されるた
め、これは必要ありません。

3.1.2 cXML 変換

cXML では、要素を使用して、従来のビジネスドキュメントでのプロパティに当たる個々の項目を記述します。たとえば、住所が子要素である番地、市区町村、国で構成されるような場合、要素は、子要素が必要な情報やそれらの子要素間の関係も記述できます。また、cXML は属性を使用して、要素の変更や内容の提供を行います。要素や属性の名前では大文字と小文字が区別され、名前の中では大文字を使用して語句を区切り、ハイフンは使用しません。要素名は大文字で始まり、属性名は小文字で始まります。たとえば、次のようになります。

要素: Sender, Credential, Payment, ItemDetail 属性:payloadID, lineNumber, domain

必須ではない要素の内容が空の場合 (null の場合)、要素全体を削除します。これは、空の要素や空白文字の要素が一部のパーサーに影響を及ぼす恐れがあるためです。DTD ファイルおよび cXML ドキュメントでは、トランザクション内で出現する要素の回数を示す記号が使用されます。「+」は、その要素が 1 回以上出現することを表し、「?」はその要素が 0 回または 1 回出現することを表し、「*」はその要素が 0 回以上出現することを表します。

3.1.3 cXML ドキュメント

cXML 要素は cXML ドキュメントのボディです。以下に、ドキュメントの先頭部分の例を示します。

cXML ドキュメントの最初の文字は、

または

でなければなりません。ドキュメントを空白文字やタブで始めることは
できません。たとえば、HTML フォームの PunchOutOrderMessage ドキュメントでは、始めの引用符と左山カッコの間に文字を挿入することはできません。cXML ドキュメントの 2 行目には、DOCTYPE 文書型宣言を入れる必要があります。これは、cXML ドキュメントで設定する唯一の外部エンティティです。この行は cXML の DTD を参照します。cXML ドキュメントには、最上位レベルの要素である cXML、Supplier、Contract、および Index。cXML 要素は、「トランザクション的」なデータの場合に使用します。その他の 3 つの要素では、静的なコンテンツを記述します。

3.1.4 ラッピングレイヤ

cXML ドキュメントは、通常は HTTP ヘッダーを持ち、HTTP を使用して転送されます。この HTTP ヘッダーでは、text/xml という MIME (Multipurpose Internet Mail Extensions) メディアタイプを指定し、さらに cXML ドキュメントのエンコード方式を示す charset パラメータを指定します。HTTP は 8 ビットクリーンであるため、受信パーサーによってサポートされる任意の文字エンコードが、base64 やquoted-printable などの content-transfer encoding を必要とせずに使用できます。すべての XML パーサーは、USASCIIを含むすべての Unicode 文字が入っている UTF-8 (Universal Transformation Format) へのエンコードをサポートしています。そのため、cXML ドキュメントを転送する場合、アプリケーションでは UTF-8 を使用してください。

cXML ドキュメントの HTTP 送信には、次の MIME と HTTP ヘッダーが含まれます。

3.1.5 添付ファイル

cXML プロトコルでは、任意のタイプの外部ファイルを cXML ドキュメントに添付することができます。たとえば、バイヤーが注文書の内容を明確にするために、補足メモ、図面、または FAX を添付する場合があります。別の例として、カタログファイルを添付する CatalogUploadRequest ドキュメントがあります。cXML ドキュメントで参照されるファイルは、受信者がアクセス可能なサーバー上に置くか、または cXML ドキュメント自身も含むエンベロープに入れることができます。cXML ドキュメントに外部ファイルを添付して 1 つのエンベロープにするには、MIME (Multipurpose Internet Mail Extensions) を使用します。cXML ドキュメントには、マルチパート MIME エンベロープで送信される外部パートへの参照が含まれます。添付ファイルを含めるこのエンベロープに対する cXML の必要条件 (IETF RFC 2046 の「Multipurpose Internet Mail Extensions Part Two: Media Types」で規定) として、Content-ID ヘッダーが添付ファイルごとに必要です。cXML で指定する URL は、cid: で開始する必要があります。これはより大規模な送信で添付ファイルを参照するための識別子です。cid: 識別子は、送信されるドキュメントを含む MIME 送信の 1 パート (1 つのみ) の Content-ID ヘッダーと一致していなければなりません。

次の例は、JPEG 画像を添付する場合の cXML ドキュメントに必要なスケルトンを示します (ただし上述の HTTP ヘッダーは含んでいません)。

さらに、このスケルトンには、受信 MIME パーサーで処理する必要があるすべてのものが含まれています。RFC 2387 の『The MIME Multipart/Related Content-type』で規定されているメディアタイプを使用するアプリケーションは、このスケルトンの内容を拡張することによって、より多くの情報を取得できます。

multipart/related メディアタイプを解読できない受信 MIME パーサーは、上記の 2 つの例を同様に処理する必要があります。MIME 転送の各パートに Content-transfer-encoding を追加して、そのエンコードを使用することもできます。HTTP 転送には、この追加は必要ありません。cXML プロトコルでは、Content-description ヘッダーと Contentdisposition ヘッダの設定は任意ですが、これらのヘッダーを使用すると文書の利用価値を高めることができます。

Attachment の例

次の例は、カタログを添付する CatalogUploadRequest を示します。

Content-ID または Content-Type ヘッダー内の ID は山カッコ (< >) で囲みます。ただし、URL 要素内で ID を参照する場合は、これらのカッコを省略します。また、URL 要素内でメッセージ ID の前に cid: を付加します。ただし、MIMEヘッダー内では付加しません。cid: URL の特殊文字は、16 進コード (%hh フォーマット) にする必要があります。テキストファイル、PDF、画像などを cXML ドキュメントに添付する場合は、Attachment 要素を使用します。ほかのcXML ドキュメントを添付する場合は、cXMLAttachment を使用します。その cXML ドキュメントにさらに添付ファイルが含まれるかどうかは関係ありません。cXMLAttachment 要素は、添付ファイルを処理するために追加の cXML 処理が必要であることを受信システムに通知します。

次の例は、cXMLAttachment を使用してファイルを添付した cXML ドキュメントを転送する CopyRequest を示します。

MIME の詳細情報

MIME 規格の詳細については、次の Web サイトを参照してください。

● www.hunnysoft.com/mime
● www.ietf.org/rfc1341.txt
● www.ietf.org/rfc/rfc2046.txt
● www.ietf.org/rfc/rfc2387.txt

3.1.6 cXML エンベロープ

cXML 要素は cXML ドキュメントのルート要素で、その他のすべての要素はこの中で定義します。cXML 要素は、すべての cXML トランザクションで定義されます。次に、cXML 要素の有効な例を示します。

cXML には次の属性があります。

属性説明
version
(非推奨)
この属性は、cXML 1.2.007 以降のバージョンでは推奨されていません。新規の cXML ドキュメントでは使用しないでください。cXML プロトコルのバージョンを指定します。検証を行う XML パーサーも、参照元の DTD からバージョン属性を確認できます。このバージョン番号は cXML ドキュメントの SYSTEM 識別子にも表示されるため、この属性は使用しないでください。
xml:langこの地域情報は、このドキュメントで送信されるすべてのフリーテキストで使用されます。受信者は同一、または類似の地域情報で応答や表示を行ってください。たとえば、Request の中でxml:lang=“en-UK” を指定したクライアントは、Response として “en” データを受信します。最も明確で特定化できる地域情報を指定してください。
payloadID
(必須)
消失した、または問題が発生したドキュメントを特定するためにロギング目的で使用される、スペースと時間に関する一意の数字。この値を変更して再試行しないでください。次のような実装を推奨します。
datetime.process id.random number@hostname
timestamp
(必須)
メッセージが送信された日付と時刻。ISO 8601 フォーマットで記述されます。この値を変更して再試行しないでください。フォーマットは、YYYY-MM-DDThh:mm:ss-hh:mm となります (2015-07-14T19:20:30+01:00 など)。
signatureVersion存在する場合には、ドキュメントが電子署名付きであることを示します。このドキュメントには、Request、Response、または Message 要素の直後に有効な ds:Signature が 1 つ以上定義されています。この属性の有効な値は 1.0 のみです。その他の値は将来の使用に備えて予約されています。
3.1.6.1 xml:lang で指定する地域情報

xml:lang 属性は、ほとんどのフリーテキスト要素 (Description や Comments など) で指定できます。XML 仕様では、ある要素に地域情報が指定されていない場合、親要素に指定された地域情報がその要素の通常の地域情報となりますが、このようにしてドキュメントツリーの検索を行って通常の値を決定すると効率が低下します。cXML では、地域情報識別子をそれに関連する文字列とともに保持するようにします。最も明確で特定化できる既知の地域情報を、この属性に指定してください。cXML プロトコルのさまざまな要素で指定できる xml:lang 属性は、番号、日付および時刻などのフォーマット済みデータには影響を与えません。次項の timestamp 属性で説明するように、timestamp 属性に関しては、それぞれの値はデータタイプに従ってフォーマットされます。マシン処理に配慮していない長い文字列 (および参照される Web ページ) には、近くにある xml:lang 属性に一致する地域固有の数値または日付フォーマットが使用される場合があります。

3.1.6.2 日付、時刻およびその他のデータタイプ

timestamp 属性と、cXML 内にあるその他すべての日付と時刻は、ISO 8601 で制限されたサブセットでフォーマットされなければなりません。この情報は、『Word Wide Web Consortium (W3C) Note』の「Date and Time Format」に記述されており、www.w3.org/TR/NOTE-datetime-970915.html で入手できます。timestamp には、少なくとも完全な形式の日付および時、分、秒が含まれている必要があります。秒の小数部の設定は任意です。このプロトコルでは、UTC (協定世界時、グリニッジ標準時としても知られます) を基準とした時間帯で現地時間を表す必要があります。「Z」時間帯識別子は使用できません。たとえば、2015-04-14T13:36:00-08:00 は、米国太平洋標準時の西暦 2015 年 4 月 14 日午後 1 時 36 分に相当します。

注記
timestamp 属性は cXML DTD で必要ですが、値のフォーマットの検証はアプリケーションに依存します。

cXML で使用する日付、時刻、およびその他のデータタイプのフォーマットに関する詳細情報は、次のサイトで参照できます。

● Microsoft 社の XML Data Types Reference: msdn.microsoft.com/library/default.asp?url=/library/en-us/xmlsdk/html/b24aafc2-bf1b-4702-bf1c-b7ae3597eb0c.asp
● W3C (Word Wide Web Consortium) に対する XML データ提案の原書: www.w3c.org/TR/1998/NOTE-XMLdata-0105

3.1.6.3 特殊文字

cXML では XML と同様に、すべての文字がキーボードから入力できるわけではありません。たとえば登録商標記号 (R)などがこれに該当します。また、たとえば < や & は、XML では特別な意味を持ちます。これらの文字は、文字エンティティを使用してエンコードする必要があります。XML では、次の組み込み文字エンティティが定義されています。

エンティティ文字
&lt;<
&gt;>
&amp;&
&quot;"
&apos;'

使用するエンコード以外の文字に関しては、シャープ記号 (#) に続けてその文字の Unicode 番号 (10 進数または 16 進数) を使用します。たとえば、 &#xAE; および &#174; は、登録商標記号 ((R)) を表します。次に例を示します。

これは、次のようにエンコードします。

一重引用符 (‘) または二重引用符 (“) が属性値の中で使用されており、その属性値がこれらの引用符で囲まれている場合、属性値の中で使用されている引用符は、エスケープする必要があります。属性値の中に引用符が含まれる場合、属性は一重引用符のみを使用して囲むことを推奨します。

3.1.6.3.1 ドキュメントにおける特殊文字の処理
  1. 属性の区切り文字として一重引用符のみを使用しているテンプレートを使用します。
  2. 次のいずれか 1 つを実行して、そのテンプレートに値を追加します。
    • ドキュメントが、cxml-urlencoded 隠しフィールドによって転送された PunchOutOrderMessage である場合、US-ASCII エンコードを使用してテンプレートに値を入力します。このエンコードでは、エンコードできないすべての文字に対して、XML 文字エンティティを使用します。たとえば、登録商標記号 (®) は、US-ASCII ではサポートされていないため、&#174; と入力します。
    • それ以外の場合は、UTF-8 エンコードを使用してドキュメントの値を入力します。HTTP Post により直接送信されたドキュメント、または cXML-base64 隠しフィールドに埋め込まれたドキュメントのすべてで、UTF-8 を使用します。UTF-8 には、US-ASCII コードがすべて含まれています。
  3. cXML ドキュメント作成時に、XML で属性値と要素の内容をエスケープします。エスケープする必要がある文字は、&、’、<、および > です。PunchOutOrderMessage ドキュメントを転送する場合は、次の手順が必要です。
  4. ブラウザが解読するすべての文字について、次のことに注意してください。
    • cxml-urlencoded 隠しフィールドを使用している場合、すべての二重引用符を " に変換します。
    • さらに (cxml-urlencoded フィールドの場合)、HTML で有効なコンテキストで記述されているすべてのアンパサンドを、& に変換してください。安全を期すために、すべてのアンパサンドをエスケープしてもかまいません。たとえば、アンパサンド (&) は & としてエスケープし、アポストロフィ (‘) は &apos; としてエスケープします。登録商標記号 (®) は &#174; としてエスケープします。
    • これ以外の場合で、cxml-base64 隠しフィールドを使用している場合、cXML ドキュメント全体に対して base64 エンコード方式を使用します。
  5. 文字列を二重引用符で囲んで、ドキュメントを HTML フォームに埋め込みます。たとえば、値が ®®””””&<>>”で、属性の値が ®®'”””&<>> の Money 要素を送信する場合、XML ドキュメントは次のようになります。

これは、次のようにエンコードしてください。

上記の例は、cXML-urlencoded フィールドをエンコードする別の方法です。ここでは XML が、山カッコなどのいくつかの文字をエスケープしないようにしていますが、これは XML での特別な処理というわけではありません。前記の手順を直接実装すると、次のような HTML フィールドになります。

または、次のような XML ドキュメントになります。

3.1.7 Header

Header 要素は、アドレス指定と認証情報で構成されます。cXML メッセージのボディに特定の Request または Response がある場合も、Header 要素は同じです。アプリケーションは申請者の ID 情報が必要ですが、ID 情報の内容が正しいかどうかの検証は行いません。次の例は、Header 要素を示しています。

From 要素と To 要素は、SMTP メールメッセージの From と To と同義です。これらは、メッセージの論理的な発信元と宛先です。Sender 要素に定義する情報は、HTTP 接続を開始して cXML ドキュメントを送信する組織または人です。Sender 要素には Credential 要素が含まれており、この要素を使用して、受信者は送信者を認証します。この認証方法は、公開鍵によるデジタル認証のためのインフラストラクチャを必要とせずに、強力な認証を可能にします。送信者は、受信者側が発行したユーザー名とパスワードを使用することで、Requests を実行できます。ドキュメントが最初に送信される時は Sender と From は同一の組織を示していますが、cXML ドキュメントがネットワークハブを経由して転送されると、Sender 要素は変更され、送信した直前の組織を示すようになります。

3.1.7.1 From

この要素は、cXML Request の発信元を識別します。

3.1.7.2 To

この要素は、cXML Request の宛先を識別します。

3.1.7.3 Sender

この要素によって、受信者側は HTTP 接続を開始した相手を識別して認証します。受信者側は作業の要求者を認証する必要があるため、この要素内では、From または To 要素の場合よりも強力な認証機能を持つ Credential 要素を使用します。

3.1.7.4 UserAgent

cXML で対話を行う UserAgent を表す、テキスト文字列です。この文字列は、製品ごとに固有にする必要があり、可能であればバージョンごとにも固有にしてください。これは、HTTP の UserAgent に類似しています。

3.1.7.5 Credential

この要素には、識別値と認証値を定義します。Credential には次の属性があります。

属性説明
domain
(必須)
認証情報のタイプを指定します。この属性を使用して、複数の認証ドメインに対する複数のタイプの認証情報をドキュメントに含めることができます。たとえば、Ariba Network 上で送信されたメッセージについて、domain にAribaNetworkUserId が指定されている場合は電子メールアドレス、DUNS の場合はDUNS ナンバー、NetworkId の場合は割り当て済みの ID を表します。
typeマーケットプレイスからの、またはマーケットプレイスへの要求は、マーケットプレイスとメンバー企業の両方を From または To Credential 要素で識別します。この場合、マーケットプレイスに対する認証情報には type 属性を使用し、その属性は「marketplace」という値に設定します。

Credential には、Identity 要素を含め、任意で SharedSecret 要素または CredentialMac 要素を含めます。Identity 要素は Credential の対象である組織について記述し、任意設定の認証要素はその組織の ID 情報を記述します。

SharedSecret

SharedSecret 要素は、申請者が認識するパスワードが Sender に含まれる場合に使用します。

注記
One-Way 転送によって送信されるドキュメントには、認証要素を使用しないでください。One-Way 転送はユーザーのブラウザを介してルーティングされるため、Credential 要素を含むドキュメントのソースをユーザーに参照される可能性があります。

CredentialMac

CredentialMac 要素は、メッセージ認証コード (MAC) による認証で使用されます。この認証方法は、信頼のおけるサードパーティにより共有シークレットを使用して認証されたことを、送信者が受信者に証明する必要がある状況で使用されます。たとえば、ダイレクトパンチアウト要求は、サプライヤによる認証が可能な MAC (ネットワークハブによって生成されたもの) が含まれるため、バイヤーからサプライヤへ、ネットワークハブを介さずに直接送信できます。信頼のおけるサードパーティが MAC を計算し、プロファイルトランザクションを介して送信者へ転送します。送信者はMAC の値しか見ることはできません (安全で逆変換できません)。MAC は、ProfileResponse オブジェクトを使用し、信頼のおけるサードパーティから送信者に送信されます。受信者は、信頼のおけるサードパーティと同じ入力データを使用して MAC を計算し、cXML ドキュメントで受信した MACと比較します。この 2 つの値が一致するとドキュメントは認証されたことになります。MAC 値の計算方法については、メッセージ認証コード (MAC) [561 ページ] を参照してください。CredentialMac には、次の属性があります。

属性説明
type
(必須)
認証されるデータとその認証用のフォーマット方法を識別します。サポートされる値は”FromSenderCredentials” のみです。
algorithm
(必須)
データで使用された MAC アルゴリズムを識別します。サポートされる値は “HMAC-SHA1-96”のみです。
creationDate
(必須)
MAC が生成された日時を指定します。
expirationDate
(必須)
MAC の有効期限を示す日時を指定します。受信者は expirationDate 後に受け取った MAC を却下する必要があります。受信者は有効期限前の MAC を、任意で却下することもできます。たとえば、受信者は 1 時間以内に有効期限が切れる MAC を却下する場合があります。

次の例は、CredentialMac 要素が使用されている Credential 要素を示します。

複数の認証情報

From 要素、To 要素、および Sender 要素には、それぞれに複数の Credential 要素を任意で設定できます。複数の認証情報を提供する目的は、さまざまなドメインを使用している 1 つの組織を識別することです。たとえば、DUNS ナンバーおよび NetworkId ナンバーの両方を含めることで、組織が識別される場合があります。

受信者は、受け取ったドメインのすべての認証情報を検証する必要があります。使用されたドメインの認証情報が、認識している組織と一致しない場合、そのドキュメントを却下してください。同じ From、To、または Sender セクションの 2 つの認証情報が別々のエンティティを参照している場合にも、ドキュメントは却下されます。異なる値が使用されているものの、同じドメインが使用されている To、From、または Sender セクションに複数の認証情報が存在する場合には、ドキュメントは却下されます。

3.1.7.6 Correspondent

From および To 要素には、任意設定の Correspondent 要素をそれぞれ含めることができます。Correspondent 要素は、発信側または受信側の組織が、もう一方の組織または接続ハブにとって未知である場合に使用されます。送信者、受信者、または接続ハブは、Correspondent 要素内の情報を使用して未知の組織を識別できます。Correspondent には次の属性があります。

属性説明
preferredLanguage組織の優先言語 (わかっている場合)
未知の組織は Contact 要素で識別します。

3.1.8 Request

クライアントは、Request ドキュメントを送信して特定の操作を要求します。cXML ドキュメントの読み取り処理を分割する必要がないよう、各 cXML エンベロープ要素で使用できる Request 要素は 1 つだけです。このため、サーバーの実装は単純になります。Request 要素には、事実上すべてのタイプの XML データを含めることができます。一般的な Request 要素として次のものがあります。

● OrderRequest
● ProfileRequest
● PunchOutSetupRequest
● StatusUpdateRequest
● GetPendingRequest
● ConfirmationRequest
● ShipNoticeRequest
● ProviderSetupRequest
● PaymentRemittanceRequest

Request には次の属性があります。

属性説明
deploymentModeRequest がテストモードであるか本稼動モードであるかを示します。値は、「production」(通常) または「test」です。
Idこの属性は要素およびそのすべての子要素を電子署名の対象として呼び出すために使用します。

3.1.9 Response

サーバーはクライアントに Response を送信して、操作結果を通知します。一部の Request の結果にはデータがない場合があるため、Response 要素は、任意で Status 要素のみで構成することもできます。さらに、Response 要素にはどのようなアプリケーションレベルのデータも含めることができます。たとえば PunchOut セッションでは、そのアプリケーションレベルのデータが PunchOutSetupResponse 要素に含まれています。一般的な Response 要素として次のものがあります。

● ProfileResponse
● PunchOutSetupResponse
● GetPendingResponse

Response には次の属性があります。

属性説明
Idこの属性は要素およびそのすべての子要素を電子署名の対象として呼び出すために使用します。
3.1.9.1 Status

この要素は要求された操作が成功したか、一時エラーか、または永久エラーかを通知します。
Status には次の属性があります。

属性説明
code
(必須)
要求の状況コード。たとえば、200 は要求が成功したことを示します。下記のコード表を参照してください。
text
(必須)
状況のテキスト。このテキストは、英語で記述された標準的なエラー表記で、ユーザーが判読できるログです。
xml:langStatus 要素で使用されるデータの言語。cXML 1.0 との互換性を目的としたオプションです。cXML の将来のバージョンで必要となる場合があります。

Status 要素の属性は、要求の結果を表します。以下に例を示します。

Status 要素の内容には、申請者が必要なあらゆるデータを記述することができますが、エラーに関する情報を記述するようにしてください。200/OK 状況コードには、データが存在しない場合があります。ただし、500/Internal ServerError 状況コードまたはその他の類似するコードには、実際の XML 解析エラーまたはアプリケーションエラーを含めることを強く推奨します。このエラーは、一方向のデバッグや相互運用性のテストをする際に役立ちます。以下に例を示します。

次の表は、cXML 状況コードの範囲を示します。

範囲意味
2xx成功
4xx永久エラー。クライアントは、再試行しないでください。このエラーの場合、申請は承認されていません。
5xx一時エラー。一般的には転送エラーです。クライアントは、再試行してください。推奨する再試行回数は、1 時間おきに 10 回です。少なくとも 6 回の再試行を推奨します。緊急なオーダーなど、重要度の高い申請に関しては、再試行頻度を上げてもかまいません。

cXML 状況コードが 200 番台 (cXML 200/OK など) でない限り、サーバーには追加の Response 要素(PunchOutSetupResponse 要素など) を含めないでください。ほとんどの場合、cXML は HTTP の上の階層にあるため、多くのエラー (HTTP 404/Not Found など) はトランスポートによって発生しています。すべてのトランスポートエラーは、cXML 500 番台の状況コードを受け取った時と同様に一時エラーとして取り扱い、クライアントは再試行する必要があります。HTTP 404/Not found や HTTP 500/Internal Server Error 状況コードなどの、有効な cXML コンテンツを含まない HTTP Response は、すべて転送エラーであるとみなされます。転送に関するその他の一般的な問題には、タイムアウト、TCP エラー (「connection refused」など)、および DNS エラー (「host unknown」など) があります。Request ドキュメントの構文解析における検証エラーの場合、一般的には 400 番台、多くは 406/Not Acceptable の cXML 永久エラーが発生します。

次の表に、発生し得る cXML 状況コードを示します。

ステータステキスト意味
200OKサーバーは Request を実行しました。または、最終受信者へ結果を送信しました。返された Response には、アプリケーションの注意またはエラーが含まれる可能性があります。cXML Request 自身はエラーも注意も生成しませんでしたが、この状況はその後のアプリケーションで発生し得るいかなるエラーや注意も、反映されません。後の処理でエラーが発生しない限り、この状況の更新情報は受け取りません。
201Accepted中間ハブによって転送の Request が受け入れられました。または、その最終の宛先によって受信されましたが、解析はされていません。送信するメカニズムが利用可能であれば、Request に関する状況の更新情報を受け取ります。クライアントはこの後 StatusUpdate トランザクションを受信します。
204NoContent すべての Request 情報は有効で、認識されました。サーバーには、要求されたタイプの Response データがありません。PunchOutOrderMessage において、この状況はパンチアウトセッションがショッピングカート (または、クライアントの購入申請) に対する変更なしに終了したことを示します。
211OKバイヤーはこの状況コードを使用して、サプライヤが把握する必要があるイベント (休日のスケジュール、生産設備の閉鎖、特定の活動の完了 (たとえば、計画実行完了) など)を通知するために、サプライヤにブロードキャストメッセージを送信することができます。
280中間ハブにより Request が転送されました。少なくとももう 1 つの状況更新情報を受け取ります。この状況は、Request が別の中間転送者、または、状況 201 で最終受信者に送信されたか、信頼できる非 cXML のトランスポートを経由して転送されたことを意味する場合があります。
281非確実なトランスポート (電子メールなど) を使用して、中間ハブにより Request が転送されました。状況更新情報を受け取る可能性があります。ただし、状況更新情報を受け取らない場合、必ずしも問題があるというわけではありません。
400Bad Request構文解析では問題がありませんが、サーバーが Request を受け入れられませんでした。
401UnauthorizedRequest (Sender 要素) の中で指定されている Credential が、サーバーに認識されませんでした。
402Payment RequiredRequest には、完全な Payment 要素が含まれていなければなりません。
403Forbiddenユーザーが、Request を実行するための十分な権限を持っていません。
406Not AcceptableRequest はサーバーに受け入れられませんでした。構文解析の失敗によるものと推測されます。
409Conflictサーバーの現在の状況またはその内部データにより、(更新) 操作要求が中断されました。同様の Request は、別の操作の実行後以外では、今後も正常に実行される可能性はありません。
412Precondition FailedRequest の前提条件 (PunchOutSetupRequest edit に対する適切なパンチアウトセッションなど) が満たされていませんでした。この状況は、一般的には、サーバーからの以前の転送の一部をクライアントが無視したことを意味します
(PunchOutOrderMessageHeader の operationAllowed 属性など)。
417Expectation FailedRequest のリソース条件が満たされなかったことを示します。1 つの例として、サーバーが未知のサプライヤに関する情報を要求する SupplierDataRequest があります。この状況は、クライアントまたはサーバーで消失した情報があることを示します。
450Not Implementedサーバーは指定の Request を実装していません。たとえば、PunchOutSetupRequest、もしくは要求された操作がサポートされていない可能性があります。一般的に、この状況はクライアントがサーバーのプロファイルを無視した
ことを示します。
475Signature Requiredドキュメントに電子署名がないため、受信者はドキュメントを受け付けようとしません。
476Signature Verification Failed転送中にドキュメントが変更、または署名で使用されたアルゴリズムの 1 つまたは複数を受信者がサポートしないなどの原因により、受信者は署名を検証することができません。
477Signature Unacceptable署名は技術的に有効ですが、その他の理由により受信者に承認されません。署名規定または証明書規定が承認されないか、使用された証明書の種類が承認されないか、またはその他の問題が存在する可能性があります。
500Internal Server Errorサーバーが Request を完了できませんでした。
550Unable to reach cXML server次の処理のための接続が必要なトランザクションは、次の cXML サーバーに到達できず完了できません。サプライヤサイトに到達できないとき、中間ハブがこのコードを返すことがあります。次への接続が完了した場合、中間ハブはエラーをクライアントに直接返さなければなりません。
551Unable to forward requestサプライヤの設定ミスにより、Request を転送できません。たとえば、中間ハブがサプライヤに対し自身の認証に失敗しました。クライアントはこのエラーを修正できませんが、クライアントが再試行する前にこのエラーが解決される場合があります。
560Temporary server errorたとえば、サーバーは保守などで停止することがあります。クライアントは後で再試行してください。

下の表は、CatalogUploadRequest に対する可能な状況コードを一覧にしたものです。

ステータステキスト意味
200SuccessCatalogUploadRequest は正常に処理されました。
201AcceptedCatalogUploadRequest を処理中です。
461Bad Commodity Codeカタログに割り当てられている商品分類コードが無効です。
462Notification Error通知方法 (電子メールまたは URL) が指定されていません。
463Bad Catalog FormatZIP ファイルが無効です。
464Bad Catalogカタログが添付されていないか、複数のカタログが添付されています。
465Duplicate Catalog Name同じカタログ名が存在します。
466No Catalog to Update更新するカタログが存在しません。
467Publish Not Allowed以前に公開されていないカタログを公開しようとしました。
468Catalog Too Largeアップロードするファイルのサイズが 4MB の制限を超えています。カタログをアップロードする前に、ZIP 形式で圧縮してください。
469Bad Catalog Extensionカタログのファイル名の拡張子は、.cif、.xml、または.zip でなければなりません。
470Catalog Has Errorsメッセージが、カタログの状況を示しています。(HasErrors)
499Document Size Error cXMLドキュメントのサイズが大きすぎます。
561Too Many Catalogs1 時間当たり一定数以上のカタログをアップロードすることはできません。
562Publish Disabled定期保守作業に伴い、カタログの公開を一時停止しています。指定した日時までに復旧する見通しです。
563Catalog Validating以前のバージョンのカタログの検証が終了する前に、カタログを更新しようとしました。

認識されないコードを受信したとき、cXML クライアントはコードのクラスに従ってそれらのコードを処理する必要があります。したがって、古いクライアントは、すべての新しい 2xx コードを 200 (成功)、4xx コードを 400 (永久エラー)、および 5xx コードを 500 (一時エラー) として処理する必要があります。この動作は、今後、相互運用性を損なわずに、cXML プロトコルとサーバー固有のコードが拡張されることを考慮しています。

3.1.10 One-Way (非同期式) モデル

Request/Response トランザクションと異なり、One-Way メッセージは HTTP 転送に限定されません。One-Way メッセージは、HTTP チャネル (同期式の Request/Response タイプの操作) で対応できないような場合に使用します。次の図は、Request/Response トランザクションを使用せず A および B がメッセージを通信する方法を示しています。

図 2: One-Way メッセージ (非同期式)

この場合、以下のシナリオが考えられます。

  1. サイト A は、サイト B が認識する転送方法で cXML ドキュメントをフォーマットしてエンコードします。
  2. サイト A は、その転送方法を使用してドキュメントを送信します。サイト A は、サイト B からの Response を待つことはしません (待ち状態になることはできません)。
  3. サイト B は、cXML ドキュメントを受信した後、それを転送ストリームからデコードします。
  4. サイト B はドキュメントを処理します。
    One-Way モデルでは、サイト A とサイト B の間に明示的な Request/Response サイクルは存在しません。たとえば、One-Way メッセージによる通信中に別の相手からメッセージが到着して、そちらの対話が始まる可能性もあります。One-Way トランザクションを完全に明記するには、メッセージの転送方法も記述します。たとえば、One-Way アプローチを使用する cXML トランザクションでは、転送方法とエンコード方式を指定します。One-Way トランザクションを使用する一般的な例は、PunchOutOrderMessage です。

One-Way メッセージの構造は、Request/Response モデルの構造と類似しています。

Header 要素は、Request/Response ドキュメントと同様に処理されます。cXML 要素も、cXML エンベロープ [24 ページ] に説明した内容と同じです。One-Way メッセージと Request/Response メッセージとの違いを見分ける最も簡単な方法は、Request または Response 要素の代わりに使用する Message 要素の有無を確認することです。次のセクションでは、Message 要素についてさらに詳しく説明します。One-Way メッセージの Header 要素の送信者認証情報に、共有シークレット情報を含めないでください。認証は、BuyerCookie を使用して行われます。これは、Request/Response の Header とは異なります。

3.1.11 Message

この要素には、cXML メッセージのすべてのボディの情報を定義します。この要素には、任意設定の Status 要素を含めることができます (Response 要素の Status 要素と同じです)。Status 要素は、Request メッセージに対する Responseメッセージ中で使用します。Message には次の属性があります。

属性説明
deploymentModeRequest がテストモードであるか本稼動モードであるかを示します。値は、「production」(通常) または「test」です。
inReplyToこの Message が応答する Message を指定します。inReplyTo 属性の値は、以前に受信した Message の payloadID です。この属性は、多数のメッセージによる双方向の対話を行う場合に使用します。
Idこの属性は要素およびそのすべての子要素を電子署名の対象として呼び出すために使用します。

inReplyTo 属性は、以前の Request または Response ドキュメントの payloadID を参照することもできます。Request/Response トランザクションが、複数の One-Way メッセージを介して「対話」を開始するとき、最初のメッセージには、逆方向へ最後に送信された適切な Request または Response の payloadID を含めることができます。たとえば、PunchOutOrderMessage を含む Message には、パンチアウトセッションを開始した PunchOutSetupRequestの payloadID を持つ inReplyTo 属性が指定されている場合があります。パンチアウトドキュメントに含まれるBuyerCookie には、この inReplyTo 属性と同様の機能があります。

3.1.12 転送オプション

One-Way メッセージには、HTTP と URL フォームエンコードの 2 つの一般的に使用される転送があります。現在明確に定義されている転送は、これら 2 つだけです。将来、さらに多くの転送がサポートされる可能性があります。

HTTP

調達アプリケーションは、One-Way HTTP 通信を使用して情報を引き出します。One-Way HTTP 通信を使用するトランザクションの 1 つに、GetPendingRequest があります。セキュリティのため転送データが暗号化されるため、HTTPS が推奨されます。

URL フォームエンコード

URL フォームエンコードを使用することにより、リモート Web サイトと調達アプリケーションの統合が可能になります。さらに、URL フォームエンコードでは、バイヤーシステムの受信サーバーを通す必要がなく、バイヤーシステムにインターネットを経由して直接アクセスできます。PunchOutOrderMessage トランザクションがどのように動作するかの説明は、この転送の仕組みを理解するのに役立ちます。リモート Web サイトは、cXML PunchOutOrderMessage ドキュメントを調達アプリケーションに直接送信するのではなく、このドキュメントを HTML Form の隠しフィールドとしてエンコードし、PunchOutSetupRequest のBrowserFormPost 要素で指定した URL の示す場所にその情報を書き込みます。ユーザーが買物の終了後に Webサイトの [チェックアウト] ボタンをクリックすると、Web サイトはそのデータを HTML Form で調達アプリケーションに送信します。下の図に、その処理を示します。

パッキングとアンパッキングについて以下で説明します。

Form パッキング

リモート Web サイトで、各 PunchOutOrderMessage ドキュメントが cXML-urlencoded または cXML-base64 という Form の隠しフィールドに割り当てられます。また、HTML Form 要素で METHOD に POST を、ACTION に PunchOutSetupRequest の BrowserFormPost 要素の中で示された URL を割り当てます。

例:

ページ上に追加された HTML タグには、ショッピングカートの内容を詳しく説明するために、上記のフラグメントが含まれることがあります。

注記
Web サーバーが cXML-urlencoded フィールドを送信したときには、URL はまだエンコードされていません。このエンコードは、フォームが Web ブラウザによって送信されるとき (上記の例で、ユーザーが [チェックアウト] をクリックしたとき) にのみ必要です。Web ブラウザ自体はこの必要条件を満たしています。Web サーバーが HTML エンコードの処理をする必要があるのは、フィールド値、エスケープのための引用符、およびその他の特殊文字のみであるため、フォームはユーザーにとって適切な形で表示されます。

名前 cXML-urlencoded and cXML-base64 では、大文字/小文字が区別されます。

cXML-urlencoded

cXML-urlencoded フィールドは、Web サーバーやサプライヤではなく、Web ブラウザによって (HTTP 仕様に従って)エンコードされた URL です。これは、たとえば前の例で、ユーザーが [チェックアウト] をクリックした場合のように、Web ブラウザによってフォームが送信された場合にのみエンコードが必要となるためです。ただし、フォームを適切な形で表示するために、Web サーバーはフィールド値、エスケープのための引用符、およびその他の特殊文字を HTML エンコード処理する必要があります。

注記
サプライヤは、cXML-urlencoded フィールドを URL エンコード処理しないでください。このフィールドは、Web ブラウザによって自動的に URL エンコードされます。

受信パーサーは、cXML-urlencoded データに関して、メディアタイプ text/xml の通常の値を超えた charset パラメータを解釈することができません。送信されたデータの文字エンコード情報は、HTTP POST では保持されません。受信Web サーバーは、隠しフィールドを含む HTML ページのエンコードを解釈できません。したがって、この方法で転送されるcXML ドキュメントでは、us-ascii 文字エンコードを使用する必要があります。XML ソースドキュメントのすべての文字(「%XX」として「URI エンコード処理」されたものを含みます) が、「US-ASCII」文字になっている必要があります。その他の Unicode 記号は、そのソースドキュメント内の文字エンティティを使用してエンコードします。

cXML-Base64

cXML-base64 の隠しフィールドは、多言語のドキュメントをサポートしています。「US-ASCII」以外の記号を含む cXML ドキュメントは、cXML-urlencoded 隠しフィールドではなく、このフィールドを使う必要があります。この方法は意味的にはほぼ同じですが、ブラウザに対する HTML エンコードや受信 Web サーバーに対する URL エンコードを使用せず、転送を通じてドキュメント全体を Base64 エンコードします。Base64 エンコードは、RFC 2045 の『Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies』で説明されています。ブラウザを介したリモート Web サイトからクライアントの受信 Web サーバーまでの Base64 エンコードでは、cXML ドキュメントの元の文字のエンコードを保持します。charset パラメータは通知される情報と一緒には届きませんが、(転送エンコードが削除された後の) デコード済みドキュメントは、メディアタイプ application/xml として処理できます。この処理によって、受信パーサーは、XML 宣言で指定されたすべての encoding 属性を受け付けることができます。このフィールド (すべての application/xml ドキュメント) に対する通常の文字エンコードは、UTF-8 です。これらの隠しフィールド (cXML-urlencoded または cXML-base64) のいずれか一方は、調達アプリケーションに送信されるデータに含まれていなければなりません。最初に検索されるのは cXML-base64 ですが、両方のフィールドを送信する必要はありません。

Form のアンパッキングと処理

事前に適切な URL を通知している調達アプリケーションは、上述の Form データを含む HTML Form POST を受信します。Form POST プロセッサは、最初に cXML-base64 変数を検索し、その値を抽出して、内容を Base64 でデコードします。このフィールドがデータに存在しない場合、Form POST プロセッサは cXML-urlencoded 変数を検索し、URL エンコードによる cXML メッセージを抽出し、それを URL デコードします。デコードされたフィールドの内容は、それが通常のHTTP Request/Response サイクルによって受信されたデータの場合と同様に処理されます。デコード後に、ドキュメントの暗黙のメディアタイプが変化して、異なる文字エンコードが指定されている可能性があります。

● cXML-urlencoded 変数の場合は、メディアタイプ text/xml を意味し、charset 属性はありません。そのため、この文字エンコードは US-ASCII に限定されます。ブラウザがエンコードを変更している可能性があるため、受信パーサーは、cXML ドキュメントの XML 宣言の encoding 属性を無視する必要があります。
● cXML-base64 変数の場合は、メディアタイプ application/xml を意味し、どのような文字エンコードも含まれる可能性があります (XML 宣言に encoding 属性がある場合は、それによって示されています)。application/xml ドキュメントの通常の文字エンコードは UTF-8, です。

このトランザクションと標準の Request/Response トランザクションとの主な相違点は、Response 送信用の HTTP 接続
がないため Response を生成しないことです。

3.1.13 サービス状況応答

このトランザクションは、特定のサービスが現在利用可能かどうかの問い合わせを解決します。HTTP GET がサービスサイトに送られると、サービスは動的に作成された有効な cXML Response ドキュメントで応答します。サービスの HTTP URL は、cXML Request ドキュメントを受信できればどこでも可能です。たとえば、https://service.ariba.com/service/transaction/cxml.asp に送信された HTTP GET は、次のような Response を受け取ります。

注記
このトランスポート (HTTP) とプロトコル (cXML) レベルの組み合せは、上記の場合に限定してください。

3.2 基本要素

以下のエンティティと要素は、cXML 仕様全体に使用できます。ここで一覧表示している定義のほとんどは、高次元のビジ
ネスドキュメントを記述するための基本的な用語です。ここでは、共通の type エンティティと、低レベルのオブジェクトを表
す共通の要素について定義します。

3.2.1 Type エンティティ

これらの定義の大部分は、W3C (World Wide Web Consortium) に Note として提出された XML-Data で定義されてい
ます。ここで定義されるいくつかの高レベル type エンティティは、XML-Data では定義されていません。

isoLangCode

ISO 639 規格による ISO 言語コードです。

isoStateCode

都道府県/州を識別する ISO 3166-2:2013 国細分コードです。ISO 3166-1 に示されている国コードとともに使用されます。

isoCountryCode

ISO 3166 規格による ISO 国コードです。

xmlLangCode

XML 1.0 仕様書によって定義される言語コード (www.w3.org/TR/1998/REC-xml-19980210.html を参照) です。一般的には、この言語コードには、ISO 639 言語コードと、ハイフンによって区切られる ISO 3166 国コード (任意設定) が含まれます。完全な XML 勧告とは異なる IANA や私的な言語コードを cXML で使用すべきではありません。IANA と私的なサブコードを使用する場合は、それらの前に正しい ISO 3166 国コードを指定してください。推奨される cXML 言語コードフォーマットは、xx[-YY[-zzz]*]? です。ここで、xx は ISO 639 言語コード、YY は ISO 3166 国コード、そして zzz は IANA または該当する言語についての私的なサブコードです。国コードは常に指定するようにしてください。言語コードは小文字、国コードは大文字で表記する規約がありますが、コードが正しく一致するための必要条件ではありません。

UnitOfMeasure

UnitOfMeasure には、製品を梱包して出荷する方法を記述します。数量単位は、数量の共通コードである UN/CEFACT 単位に準拠していなければなりません。参照資料 www.unece.org/cefact/codesfortrade/codes_index.html を参照してください。

URL

HTTP/1.1 規格によって定義された URL (Uniform Resource Locator) です。

3.2.2 ベース要素

この項で説明する要素は、Name や Extrinsic などの一般的な要素から Money などの特定の要素まで、仕様全体に使用されます。

Money

Money 要素には、currency、alternateAmount、および alternateCurrency. の 3 つの属性があります。currency と alternateCurrecy 属性は、必ず ISO 4217 で規定された 3 文字の通貨コードにしてください。Money 要素と aternateAmount (代替通貨) 属性の値は、数値でなければなりません。

例:

任意設定の alternateCurrency と alternateAmount 属性は同時に使用し、代替通貨の金額を指定します。これらは、ユーロのような二重通貨をサポートするためにも使用できます。

例:

注記
任意で 3 桁ごとに区切りのカンマを使用することができます。小数点の代わりにカンマを使用しないでください。

State

都道府県/州または国細分識別子が含まれます。PostalAddress 要素の中で定義します。これには、任意設定の isoStateCode [42 ページ] 属性があります。

所在地の項で指定する国名です。PostalAddress 要素の中で定義します。これには、任意設定の isoCountryCode[42 ページ] 属性があります。

CountryCode

国コードに対応した、ITU 電話コードです。エスケープコードの後に電話キーパッドから入力して、該当の国に接続します。TelephoneNumber 要素で使用されます。

連絡先

Contact 要素には、現在のトランザクションにとって重要などのような連絡先に関する情報も定義できます。

例: