- XML -SOAP （常に）およびREST要求（それほど頻繁ではない）で使用されます。
- JSON -RESTリクエストで使用されます。
今日はXMLを紹介します。
XML英語から翻訳、電子X tensible M ARKUP Lのanguageは、拡張可能なマークアップ言語です。データの保存と送信に使用されます。したがって、APIだけでなくコードでも確認できます。
この形式は、World Wide Web Consortium（W3C）によって推奨されているため、APIを介してデータを転送するためによく使用されます。SOAP APIでは、これは通常、入力データと出力データに使用できる唯一の形式です。
参照：
APIとは-APIの
概要SOAPとRESTの概要：それとは何か、何と一緒に食べるか-SOAPとRESTの違いに関するビデオ。
それで、それがどのように見えるか、それを読む方法、そしてそれを壊す方法を理解しましょう！はい、はい、しかしそれなしではどこに？結局のところ、送信されたデータの曲線形式にシステムがどのように反応するかを知る必要があります。
コンテンツ
XMLのしくみ
Dadataのフルネームヒントの ドキュメントから例を見てみましょう：
<req>
<query> </query>
<count>7</count>
</req>そして、このエントリが何を意味するのかを理解しましょう。
タグ
XMLでは、すべての要素をタグでラップする必要があります。タグは、山括弧で囲まれたテキストです。
<tag>山かっこ内のテキストはタグ名です。
常に2つのタグがあります：
- オープナー-山括弧内のテキスト
<tag> - 締めくくり-同じテキスト（これは重要です！）ですが、記号「/」が追加されています
</tag>
ああ、大丈夫、捕まった！常にではない。空の要素もあり、それらには1つのタグがあり、同時に開くことと閉じることの両方があります。しかし、それについては後で詳しく説明します。
タグの助けを借りて、「ここで要素が始まり、ここで終わる」というシステムを示します。それは道路標識のようなものです：
-街の入り口にその名前が書かれています：モスクワ
-出口に同じ名前が書かれていますが、取り消し線が引かれています：
*昔Yandexの記事で読んだ道路標識の例ですが、リンクを覚えていません。そして素晴らしい例です！
ルート要素
すべてのXMLドキュメントにはルート要素があります。これは、ドキュメントの最初と最後のタグです。REST APIの場合、ドキュメントはシステムが送信する要求です。または彼女が得る答え。
このリクエストを表すには、ルート要素が必要です。でツールチップ、ルート要素は「REQ」です。
別の呼び方をすることもできます。
<main><sugg>はい、何でも。それは私たちの要求の始まりと終わりを示しており、それ以上のものではありません。しかし、その中にはすでにドキュメントの本文、つまりリクエスト自体があります。外部システムに渡すパラメータ。もちろん、それらもタグに含まれますが、ルートタグではなく通常のタグに含まれます。
アイテム値
要素の値は、開始タグと終了タグの間に格納されます。数字、文字列、またはネストされたタグにすることができます！
ここに「query」タグがあります。これは、ツールチップに送信するリクエストを示します。
内部-リクエストの値。
「VictorIvan」という行をGUI（グラフィカルユーザーインターフェイス）に
挿入したかのようです。ユーザーは余分なストラップを必要とせず、美しいフォームが必要です。しかし、システムはどういうわけか「ユーザーがこれを正確に入力した」ことを伝える必要があります。渡された値の始まりと終わりを彼女に示すにはどうすればよいですか？それがタグの目的です。
システムは「query」タグを確認し、その中に「プロンプトを返す必要のある文字列」があることを理解します。
パラメータ数= 7応答で返すヒントの数を示します。Dadataのデモフォームにヒントを入れると、7つのヒントが返ってきます。これは、値count = 7がそれに縫い付けられているためです。ただし、メソッドのドキュメントを参照すると、カウントは1から20まで選択できます。
f12の[ネットワーク]タブから開発者コンソールを開き、サーバーに送信されているリクエストを確認します。あるでしょう、カウント= 7。
参照：
テスターが開発者パネルについて知っておくべきこと-コンソールの使用方法の詳細をご覧ください。
注意：
- ビクターイワン-文字列
- 7-番号
しかし、両方の値は引用符なしで来ます。XMLでは、文字列値を引用符で囲む必要はありません（ただし、JSONではそれを行う必要があります）。
要素の属性
要素は1つ以上の属性を持つことができます。フォーム内のスペースで区切られたタグ名の後に、ティアオフタグ内でそれらを示します
_ = « »例えば：
<query attr1=“value 1”> </query>
<query attr1=“value 1” attr2=“value 2”> </query>
なぜこれが必要なのですか？属性から、API要求を受信するシステムは、受信したものをまったく理解します。
たとえば、システムでOlegという名前のクライアントを検索します。簡単なリクエストを送信します。
<query></query>そしてその見返りに、オレグのパック全体を手に入れます！生年月日、電話番号、その他のデータが異なります。検索結果の1つが次のようになっているとしましょう。
<party type="PHYSICAL" sourceSystem="AL" rawId="2">
<field name=“name"> </field>
<field name="birthdate">02.01.1980</field>
<attribute type="PHONE" rawId="AL.2.PH.1">
<field name="type">MOBILE</field>
<field name="number">+7 916 1234567</field>
</attribute>
</party>このエントリを見てみましょう。主要な要素のパーティーがあります。
これには3つの属性があります。
- type = «PHYSICAL» — . , : , , . , . ! , , — ,
- sourceSystem = «AL» — . , , .
- rawId = «2» — . , , . , ? sourceSystem + rawId!
パーティー 内にはフィールド要素があります。フィールド
要素にはname属性があります。属性値はフィールド名です：名前、生年月日、タイプ、または電話番号。これは、特定のフィールドの下に隠されているものを理解する方法です。 これは、箱入りの製品と10人以上の顧客がいる場合のサポートの観点から便利です。各顧客には、独自のフィールドのセットがあります。システムにINNがある人、ない人、生年月日について重要な人、そうでない人などです。 ただし、モデルの違いにもかかわらず、すべての顧客は1つのXSDスキーマ（要求と応答を説明する）を持ちます。- パーティ要素があります。 -フィールド要素があります。
-各フィールド要素には、フィールドの名前を格納するname属性があります。
ただし、フィールドの特定の名前をXSDで記述することはできなくなりました。彼らはすでに「TKを見て」います。もちろん、顧客が1人だけの場合、または自分用または「一般的にすべての人用」のソフトウェアを作成している場合は、名前付きフィールド、つまり「話す」タグを使用する方が便利です。このアプローチの利点は何ですか。
-XSDを読み取ると、実際のフィールドがすぐに表示されます。 TKは古くなっている可能性があり、コードは最新のものになります。
-リクエストはSOAPUiで手動で簡単にプルできます-必要なすべてのフィールドがすぐに作成されます。値を入力するだけです。これはテスターにとって便利です+顧客は時々このようにテストします、彼も良いです。
一般に、どのアプローチにも存在する権利があります。あなたにとってより便利なプロジェクトを見る必要があります。私の例では、話すことのない要素の名前があります。フィールド。しかし、属性によって、あなたはそれが何であるかをすでに理解することができます。フィールド
要素に加えて、パーティには属性要素があります。xml表記とビジネスリードを混同しないでください。
- ビジネスの観点からは、これは個人の属性であるため、要素の名前-属性。
- xmlの観点からは、これは要素（属性ではありません！）であり、単に属性と呼ばれていました。XMLは、要素にどのように名前を付けるかを（ほとんど）気にしないので、問題ありません。
属性 要素には次の属性があります。
- type = "PHONE" -属性タイプ。結局のところ、それらは異なる可能性があります：電話番号、住所、電子メール...
- rawId = "AL.2.PH.1" -ソースシステムの識別子。更新に必要です。結局のところ、1つのクライアントが複数の電話を持つことができますが、IDなしで更新されている電話をどのように理解できますか？
これがXMLであることが判明しました。そして簡素化。個人が保存されている実際のシステムでは、はるかに多くのデータがあります。個人自身の約20フィールド、いくつかのアドレス、電話番号、電子メールアドレス...
しかし、どこにあるかを知っていれば、巨大なXMLでも読むのは難しくありません。また、フォーマットされている場合、ネストされた要素は右にシフトされ、残りは同じレベルになります。フォーマットしないと難しいでしょう...
そしてすべてがとてもシンプルです-タグで囲まれた要素があります。タグの中には要素の名前があります。名前の後にスペースで区切られたものがある場合：これらは要素の属性です。
XMLプロローグ
XMLドキュメントの上部に、次のようなものが表示されることがあります。
<?xml version="1.0" encoding="UTF-8"?>この行はXMLプロローグと呼ばれます。ドキュメントで使用されているXMLのバージョンとエンコーディングが表示されます。プロローグはオプションですが、存在しない場合は問題ありません。ただし、そうである場合は、XMLドキュメントの最初の行である必要があります。
UTF-8は、XMLドキュメントのデフォルトのエンコーディングです。
XSDスキーマ
XSD（X ML S chema D efinition）はXML記述です。それはどのように見えるべきですか、それはどうあるべきですか？これはマシンの言語で書かれたTKです-結局のところ、私たちはスキーマを書きます...これもXML形式です！結果は、別のXMLを記述するXMLです。
秘訣は、スキームに従ったチェックをマシンに委任できることです。また、開発者はすべてのチェックをスケジュールする必要さえありません。「ここに図があります、確認してください」と言えば十分です。
SOAPメソッドを作成する場合は、スキーマで次のことを示します。
- リクエストにはどのフィールドが含まれますか。
- 応答にはどのフィールドが含まれますか。
- 各フィールドにあるデータの種類。
- 必須のフィールドと不要なフィールド。
- フィールドにはデフォルト値がありますか、それは何ですか。
- フィールドに長さ制限はありますか？
- フィールドに他のパラメータがありますか？
- ;
- ...
さて、リクエストが来たら、まずスキームに従って正しいかどうかをチェックします。リクエストが正しければ、メソッドを起動してビジネスロジックを作成します。そして、それは複雑でリソースを大量に消費する可能性があります！たとえば、数百万ドルのデータベースからサンプルを作成します。または、さまざまなデータベーステーブルに対して12のチェックを
実行します...では、クエリが明らかに「不良」である場合、なぜ複雑なプロシージャを実行するのでしょうか。そして、すぐにではなく、5分後にエラーを出しますか？スキーマ検証は、システムに過負荷をかけることなく、明らかに無効な要求をすばやく除外するのに役立ちます。
さらに、一部のクライアントプログラムは、要求の送信に対して同様の保護を設定します。たとえば、SOAP Uiは、整形式のxmlのリクエストをチェックできますが、失敗した場合はサーバーに送信されません。データ転送の時間を節約できます。
また、SOAP APIの単純なユーザーの場合、スキーマはリクエストの作成方法を理解するのに役立ちます。「シンプルユーザー」とは何ですか？
- APIを使用するシステムの開発者-自分のシステムから自分のシステムに送信する内容を正確にコードに記述する必要があります。
- このAPIをチェックする必要があるテスター-彼はリクエストがどのように形成されるかを理解する必要があります。
はい、はい、理想的には、すべてが十分に説明されている詳細なTKがあります。しかし、悲しいかな、ああ、これは常にそうであるとは限りません。TKが単に存在しない場合もあれば、古くなっている場合もあります。ただし、コードが更新されるとスキーマが更新されるため、スキーマが廃止されることはありません。また、リクエストがどのように表示されるかを理解するのに役立ちます。
要約すると、SOAPAPIを開発するときにスキーマがどのように使用されるか。
- 私たちの開発者は、APIリクエストのXSDスキーマを作成します。そのようなデータタイプを使用して、そのような子を持つ要素を渡す必要があります。これらは必須ですが、そうではありません。
- 私たちと統合されている顧客システムの開発者は、この図を読み、それに応じて要求を作成します。
- カスタマーシステムがリクエストを送信します。
- 私たちのシステムはXSDによってリクエストをチェックします-何かが間違っている場合、それはただの揺れです。
- XSD要求が検証に合格した場合は、ビジネスロジックをオンにしてください。
それでは、回路がどのように見えるか見てみましょう！たとえば、UsersのdoRegisterメソッドを取り上げます。リクエストを送信するには、メール、名前、パスワードを渡す必要があります。クエリを正しく書く方法と間違って書く方法はたくさんあります。
| 正しいリクエスト | 無効なリクエスト |
|---|---|
|
必須の名前フィールドはありません |
|
タグ名のタイプミス（メールではなくメール） |
| ..。 | ..。 |
そのための図を書いてみましょう。リクエストには、タイプ「string」（文字列）の3つの要素（メール、名前、パスワード）が含まれている必要があります。私たちは書く：
<xs:element name="doRegister ">
<xs:complexType>
<xs:sequence>
<xs:element name="email" type="xs:string"/>
<xs:element name="name" type="xs:string"/>
<xs:element name="password" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>そして、サービスのWSD1では、さらに簡単に記述されています。
<message name="doRegisterRequest">
<part name="email" type="xsd:string"/>
<part name="name" type="xsd:string"/>
<part name="password" type="xsd:string"/>
</message>もちろん、スキーマにはインライン要素以上のものが存在する可能性があります。これらは、数値、日付、ブール値、さらには独自のタイプの一部にすることができます。
<xsd:complexType name="Test">
<xsd:sequence>
<xsd:element name="value" type="xsd:string"/>
<xsd:element name="include" type="xsd:boolean" minOccurs="0" default="true"/>
<xsd:element name="count" type="xsd:int" minOccurs="0" length="20"/>
<xsd:element name="user" type="USER" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>スキーマ内の別のスキーマを参照することもできます。これにより、コードの記述が容易になります。スキーマをさまざまなタスクに再利用できます。
参照： XSD-
スマートXML -habrの便利な記事
XSDスキーマ定義言語-XSD
スキーマ記述言語（XML-Schema） を使用できる値を持つ便利なテーブルがあります
チュートリアル 公式サイトw3.orgのXMLスキーマの例
練習：リクエストを書く
これで、APIメソッドのリクエストをXML形式で「読み取る」方法がわかりました。しかし、TKに従ってそれをどのように作成するのですか？やってみよう。ドキュメントを確認します。そしてそれが私がDadataから例を挙げている理由です-それは素晴らしいドキュメントです！
「An」で始まる女性の名前のみを返したい場合はどうすればよいですか？元の例を見てみましょう。
<req>
<query> </query>
<count>7</count>
</req>まず、リクエスト自体を変更します。今では「VictorIvan」ではなく「An」です。
<req>
<query></query>
<count>7</count>
</req>次に、TKを見てみましょう。女性のヒントだけを返す方法は？特別なパラメータがあります-性別。パラメータ名はタグの名前です。そして、私たちはすでに床を中に入れました。英語で「女性」になりますFEMALEもドキュメントで、。受け取った合計：
<req>
<query></query>
<count>7</count>
<gender>FEMALE</gender>
</req>不要なものは削除できます。ヒントの数を気にしない場合は、countパラメーターを破棄します。結局のところ、ドキュメントによると、それはオプションです。リクエストを受け取りました：
<req>
<query></query>
<gender>FEMALE</gender>
</req>それで全部です！例として、1つの値を変更し、1つのパラメーターを追加し、1つを削除しました。それほど難しいことではありません。特に詳細な仕様と例がある場合）））
自分で試してみてください！ユーザーにMagicSearch
メソッドのリクエストを書き込みます。私たちは、緊急の課題がぶら下がっている完全な偶然によってすべてのイワノフを見つけたいと思っています。
整形式のXML
どのXMLが正しいか、どれが正しくないかを決定するのは開発者の責任です。しかし、違反できない一般的なルールがあります。XMLは整形式である必要があります。つまり、構文的に正しい必要があります。
XMLの構文を確認するには、任意のXML Validator（およびgoogle）を使用できます。w3schoolsサイトをお勧めします。検証ツール自体と、例を含む一般的なエラーの説明があります。
完成したバリデーターで、XML（たとえば、サーバーへの要求）を挿入し、すべてが正常かどうかを確認します。ただし、自分で確認することはできます。構文ルールを確認し、クエリがそれらに従っているかどうかを確認します。
整形式のXMLルール：
- ルート要素があります。
- 各要素には終了タグがあります。
- タグは大文字と小文字が区別されます！
- 要素の正しい入れ子が尊重されます。
- 属性は引用符で囲まれています。
各ルールを確認し、それらをテストに適用する方法について説明しましょう。つまり、整形式のxmlと照合してクエリを正しく「分割」する方法です。なぜこれが必要なのですか？システムからのフィードバックを見てください。エラーのテキストから、どこで失敗したかを正確に理解できますか？
参照：
エラーメッセージもドキュメントです。テストしてください。-エラーメッセージをテストする理由
1.ルート要素があります
2つのXMLを並べて、「システムは、これらが1つではなく2つの要求であると自動的に判断する」と想定することはできません。わかりません。あなたがすべきではないので。
また、共通の親がない状態で複数のタグが連続している場合、これは不適切なxmlであり、整形式ではありません。ルート要素は常に存在する必要があります。
| 番号 | はい |
|---|---|
「test」と「dev」の要素がありますが、それらは隣り合っていますが、ルートはなく、その中にすべてがあります。2つのXMLドキュメントのように見えます |
そしてここには、ルートである資格要素がすでにあります |
この状態をテストするために何をしていますか？そうです、リクエストからルートタグを削除します！
2.各要素には終了タグがあります
ここではすべてが単純です。タグがどこかで開いている場合は、どこかで閉じる必要があります。壊れたいですか？要素の終了タグを削除します。
ただし、ここでは1つのタグが存在する可能性があることに注意してください。要素が空の場合は、最後にタグを閉じることで1つのタグを使用できます。
<name/>これは、空の値を渡すのと同じです
<name></name>同様に、サーバーは空のタグ値を返すことができます。FullUpdateUserメソッドでユーザーに空のフィールドを送信してみることができます。そして、リクエストではこれは許容され（name1フィールドを空に送信しました）、SOAP Ui応答では、空のフィールドを正確にレンダリングします。
合計-開始タグがある場合は、終了タグが必要です。または、最後にスラッシュが付いた1つのタグになります。
テストのために、リクエスト内の終了タグをすべて削除します。
| 番号 | はい |
|---|---|
|
|
|
|
3.タグは大文字と小文字を区別します
彼らが最初のものを書いたように-私たちはまた、最後のものを書きます。類似！そして、あなたが望んでいた方法ではありません。
ただし、テストのために、パーツの1つのレジスタを変更します。そのようなXMLは無効になります
| 番号 | はい |
|---|---|
|
|
4.要素の正しいネスト
要素は次々に移動できます1
つの要素を別の要素にネストできますが
、要素を互いにオーバーラップさせることはできません。
| 番号 | はい |
|---|---|
|
|
|
|
5.属性は引用符で囲まれています
属性を数字と考えても、引用符で囲まれます。
<query attr1=“123”> </query>
<query attr1=“” attr2=“123” > </query>テストの目的で、引用符なしで合格しようとします。
<query attr1=123> </query>合計
XML（e X tensible M arkup L anguage）は、データの保存と転送に使用されます。
— API-. SOAP-, . SOAP XML. REST, — XML, JSON.
— XML . , . XML - , , - .
XML open-source folks. , JacksonJsonProvider, «» — , (featuresToEnable), , (featuresToDisable).
XML形式は標準に従います。構文的に正しくない要求はサーバーにも送信されず、クライアントはそれをカットします。最初に整形式、次にビジネスロジック。
整形式のXMLルール：
- ルート要素があります。
- 各要素には終了タグがあります。
- タグは大文字と小文字が区別されます！
- 要素の正しい入れ子が尊重されます。
- 属性は引用符で囲まれています。
テスターの場合、XMLクエリをテストするときは、必ずすべてのルールを破るようにしてください。はい、システムはそのようなエラーを処理し、適切なエラーメッセージを返すことができるはずです。しかし、彼女はいつもこれをするわけではありません。
また、システムが公開されていて、誤った要求に対して空の応答を返す場合、それは悪いことです。別のシステムの開発者はリクエストでそれを修正しますが、空の答えでは正確にどこにあるのかさえ理解できないからです。そして、それはサポートをせがむでしょう：「私に何が問題なのですか？」、ソースコードのスクリーンショットの形で少しずつ情報を投げます。それが必要ですか？番号？次に、システムが明確なエラーメッセージを表示することを確認してください。
参照：XMLXMLチュートリアル
とはXMLを学ぶ。 Eric Ray（XML Book）XMLおよびXLSTに関する注記
PS-私のブログで「役に立つ」というタグの下でもっと役立つ記事を探してください。そして、便利なビデオは私のyoutubeチャンネルにあります