azure-rest-api-specs - Microsoft Azure の REST API 仕様のソース。
(The source for REST API specifications for Microsoft Azure.)
Azure REST API の仕様
形容
このリポジトリは、Microsoft Azure の REST API 仕様の正規のソースです。
はじめ
Azure SDK ライブラリ リリースのすべてのリポジトリと手順に関する情報を探しているマイクロソフトの従業員は、Azure SDK - 内部 Wiki にアクセスしてください。Wiki にアクセスするには、Azure SDK リリース パートナー セキュリティ グループへのアクセスを要求する必要があります。これは MyAccess グループであり、参加リクエストはマネージャーの承認が必要です。
外部の共同作成者は、「OpenAPI 仕様の使用開始」を参照してください。
用語
-
オファリング、SKU、および機能 - これらは、エコマネージャーとサービスツリーで表される個別のエンティティです。オファリング/SKU/機能エンティティと階層は外部で販売される製品を表しますが、サービス ツリーのサービス/コンポーネント エンティティは、これらの外部製品に電力を供給する対応するエンジニアリング エンティティを表します。詳細については、「製品分類」を参照してください。
-
リソース プロバイダー - サービスが新しい機能を ARM にオンボードする場合は、リソース プロバイダーの登録を完了する必要があります。既存のリソース プロバイダーからサービスへのマッピングについては、「リソース プロバイダーをサービスに一致させる」を参照してください。*
ディレクトリ構造
ディレクトリの構造は、次の規則に厳密に従う必要があります。
-
プロファイル: プロファイルフォルダには、プロファイルの定義ファイルが含まれています。プロファイル定義は、Azure Stack 一般提供バージョンと Azure クラウドで実行できるハイブリッド アプリケーションを対象としています。
-
仕様: このフォルダーは、すべての仕様 (管理プレーンとデータ プレーン) 関連ドキュメントのルート フォルダーです。
-
{RP-Name} フォルダー - 各リソース プロバイダーには、少なくとも 1 つの個別のフォルダーが必要です。
複数のフォルダが必要な場合は?これは、次の考慮事項によって異なります。
- RP フォルダーは、別の SDK パッケージにつながります。異なるサービス/コンポーネントエンティティ用に個別のSDKパッケージを持つことが期待されていますか?
- 1 つのフォルダー内のサービス/コンポーネント エンティティは、同じバージョン管理サイクルを共有します。1 つのフォルダー内のサービス/コンポーネント エンティティが同じバージョン ラベルを共有し、将来一緒にアップグレードできますか?
- 1 つの RP フォルダ内の仕様ファイルと AutoRest 構成ファイルは、同じ RP フォルダ内のファイルを参照する方が適切です。注: RP フォルダー間で参照する必要があるエンティティ型定義は、フォルダー共通タイプの下に配置および管理する必要があります。
- 詳細については、APIデザインレビューのレビュー担当者に相談してください。レビューを開始するには、Azure SDK の摂取アンケートを送信してください。
RP フォルダーには、リソース マネージャーまたはデータ プレーンの Cadl 仕様が含まれている場合があります。Cadl は、クラウド サービス API を記述し、他の API 記述言語、クライアントとサービスのコード、ドキュメント、およびその他の資産を生成するための言語です。詳細については、CADL リポジトリ: Cadl チュートリアルのチュートリアルを参照してください。また、内部 Teams チャネルの Cadl ディスカッションでフィードバックを提供するための質問をすることもできます。
リポジトリ内の Cadl ファイルの構造の詳細については、「 Cadl リポジトリの構造」を参照してください。
-
「リソースマネージャ」フォルダと「データプレーン」フォルダ:RPは、仕様を(ARMリソース用)と(その他すべて)の2つのカテゴリのいずれかに入れることができます。RP の AutoRest 構成ファイル () が存在する場合は、これらの両方のフォルダー内に存在する必要があります。
resource-manager
data-plane
readme.md
-
'マイクロソフト。{ARMNamespace}' フォルダー: フォルダーは 'リソース マネージャー' フォルダーの下にのみ必要です。つまり、管理プレーン API 仕様のみがファイル パスに ARM 名前空間を持つ必要があります。ARM 名前空間と ARM オンボーディングについては、RP オンボーディングの ARM wiki を参照してください。
-
'プレビュー' フォルダーと "安定" フォルダー: これは、サービス/コンポーネントのライフサイクル ステージ (プレビューと GA) にマップされます。たとえば、サービスがプレビュー段階にある場合は、プライベート プレビューまたはパブリック プレビューに関係なく、サービスの API 仕様をフォルダーに配置する必要があります。サービスが GA されているが、コンポーネントがプレビュー段階の場合は、プレビュー コンポーネント エンティティを含む API バージョンもフォルダーに配置する必要があります。フォルダーには、GAed サービスとすべての GAed コンポーネントの API バージョンが含まれている必要があります。
preview
preview
stable
Azure 破壊的変更ポリシーは、フォルダー内の API 仕様にどのように適用されますか?実際、リポジトリがパブリックかプライベートかにより関連しています。
preview
stable
-
プライベート プレビューまたは制限付きパブリック プレビュー (AFEC の背後または表示されるサブスクリプションの管理) のコンポーネントまたはリソースの種類を含む API 仕様は、プライベート リポジトリ (azure-rest-api-specs-pr) で PR レビューを開始することをお勧めします。また、これらの API 仕様には破壊的変更はありません。
-
一方、パブリック リポジトリのメイン ブランチで公開されているもの (azure-rest-api-specs) はすべて、フォルダー内またはフォルダー内に関係なく、Azure のお客様との契約として扱う必要があり、Azure の破壊的変更ポリシーに従う必要があります。
preview
stable
-
-
API バージョン フォルダー: このフォルダーは、OR フォルダーの直接の子です。このフォルダーには、REST API 仕様とフォルダーが含まれています。
preview
stable
examples
-
'examples' フォルダ: サンプル フォルダには x-ms-examples ファイルが含まれます。API またはリソースの種類のバージョンが異なる場合があるため、API またはリソースのバージョン フォルダーの下に配置されます。
注: フォルダ名とファイル名に関する一般的なガイダンス:
specification
- フォルダ名は単数形でなければなりません(つまり、 'プロファイル'ではなく 'プロファイル')-これは英語を話さない人のあいまいさを取り除きます。
- 一般的なフォルダー名は小文字にする必要があります
- 名前空間フォルダはパスカルケースにすることができます(つまり、 "KeyVault")
- ファイルは、あなたがあなたの魂に良いと思うどんなケースでもあります。
構造は次のようになります。
.
\---specification
| +---automation
| | \---resource-manager
| | +---Microsoft.Automation
| | | \---stable
| | | \---2015-10-31
| | | \---examples
| | \---readme.md
| +---batch
| | +---data-plane
| | | +---stable
| | | | +---2016-07-01
| | | | | \---examples
| | | | \---2017-01-01
| | | | \---examples
| | | +---preview
| | | | \---2017-05-01-preview
| | | | \---examples
| | | \---readme.md
| | \---resource-manager
| | +---Microsoft.Batch
| | | \---stable
| | | +---2015-12-01
| | | | \---examples
| | | +---2017-01-01
| | | | \---examples
| | | \---2017-05-01
| | | \---examples
| | \---readme.md
| \---playfab
| +---Playfab
| | \---cadl-project.yaml
| | \---main.cadl
| \--resource-manager
| +---Microsoft.Playfab
| | +---stable
| | | \---2017-02-27-preview
| | | \---examples
| | \---preview
| | \---2017-04-24-preview
| | \---examples
| \---readme.mdサービスグループのフォルダ構造
サービスグループのAPI仕様に取り組んでいる場合は、以下のようにフォルダ構造を構築することを選択できます。このフォルダー構造により、複数のサービス チームのコラボレーションの柔軟性が向上し、特に次のものがサポートされます。
- バージョン管理サイクルの異なる複数のコンポーネント/サービスのAPI定義を1つのrpフォルダーに収集するには
- 同じ rp フォルダーの下にあるサービスまたはコンポーネント間でいくつかの共通のエンティティ型を共有する。
次のフォルダー構造サンプルでは、'リソースマネージャー' フォルダーのみがあります。「data-plane」フォルダの下に同様のフォルダ構造が存在する可能性がありますが、サブコンポーネント/サブサービスフォルダは同じではない可能性があります。
フォルダー構造を初めて作成する場合、または現在のフォルダー構造を変更する場合は、API 仕様とツールのサポートを参照してください。
.
\---specification
| +---compute
| | \---resource-manager
| | +---Microsoft.Compute
| | | +---compute
| | | | \---stable
| | | | \---2021-11-01
| | | | +---compute.json
| | | | +---runCommands.json
| | | | \---examples
| | | +---sku
| | | | \---stable
| | | | \---2021-07-01
| | | | +---skus.json
| | | | \---examples
| | | +---disk
| | | | \---stable
| | | | \---2021-12-01
| | | | +---disk.json
| | | | \---examples
| | | +---gallery
| | | | \---stable
| | | | \---2021-10-01
| | | | +---gallery.json
| | | | \---examples
| | | +---sharedgallery
| | | | \---stable
| | | | \---2021-07-01
| | | | +---sharedGallery.json
| | | | +---communityGallery.json
| | | | \---examples
| | | +---cloudService
| | | | \---stable
| | | | \---2021-03-01
| | | | +---cloudService.json
| | | | \---examples
| | | \---common-types
| | | \---v1
| | | \---entity-types.json
| | |
| | \---readme.mdAutoRest構成ファイル(別名 readme.md)がサブサービス/サブコンポーネントフォルダの外に配置されている場合、すべてのサブサービス/サブコンポーネントを保持するSDKパッケージは1つだけになります。ファイルが各サブサービス/サブコンポーネントフォルダーに配置されている場合、各サブサービス/サブコンポーネントの個別のSDKパッケージがあります。SDK 生成用の AutoRest 構成ファイルを統合する場合は、SDK パッケージ化戦略に関する Azure SDK ArchBoard を必ず参照してください。
共通タイプ
1 つの RP フォルダ内の仕様ファイルと AutoRest 構成ファイルは、同じ RP フォルダ内のファイルを参照する方が適切です。リソースプロバイダやサービス間で共有できるエンティティ型定義は、仕様書の共通型フォルダの下、またはサービスグループフォルダ構造の共通型フォルダの下に配置・管理する必要があります。前者は rp フォルダー間でエンティティタイプ共有をサポートし、後者は同じ rp フォルダー内のコンポーネントまたはサービス間で共有するエニシティタイプをサポートします。
.たとえば、リソース管理共通タイプを参照してください。
次のステップ
仕様が完成した後のプロセスの次のステップは、SDK と API リファレンス ドキュメントを生成することです。マイクロソフトの従業員の場合は、Azure SDK - 内部 Wiki で詳細を確認してください。
外部の共同作成者は、「OpenAPI 仕様の使用開始」を参照してください。
このプロジェクトでは、マイクロソフト オープンソース行動規範を採用しています。詳細については、行動規範に関するFAQを参照するか、追加の質問やコメントがある場合は opencode@microsoft.com にお問い合わせください。
