azure-rest-api-specs - Microsoft Azure の REST API 仕様のソース。

(The source for REST API specifications for Microsoft Azure.)

Created at: 2015-07-15 02:37:13
Language:
License: MIT

Azure REST API Specification

説明: __________

このリポジトリは、Microsoft Azure の REST API 仕様の標準的なソースです。

はじめ

Azure SDK ライブラリ リリースのすべてのリポジトリと手順に関する情報を探しているマイクロソフトの従業員である場合は、Azure SDK - 内部 Wiki にアクセスしてください。Wiki にアクセスするには、Azure SDK リリース パートナー セキュリティ グループへのアクセスを要求する必要があります。これは MyAccess グループであり、参加リクエストは上司の承認を受ける必要があります。

外部コントリビューターは「OpenAPI 仕様入門」を読むことができます。

用語

  • オファリングSkus、および機能 - これらは、エコマネージャーとサービスツリーで表される個別のエンティティです。オファリング/スク/フィーチャーのエンティティと階層は外部で販売されている製品を表しますが、サービス ツリーのサービス/コンポーネント エンティティは、これらの外部製品に一緒に動力を与える対応するエンジニアリング エンティティを表します。詳細については、「製品分類」を参照してください。

  • リソース プロバイダー - サービスが新しい機能を ARM にオンボードする場合、リソース プロバイダーの登録を完了する必要があります。既存のリソース・プロバイダーからサービスへのマッピングについては、「リソース・プロバイダーとサービスのマッチング」を参照してください。*

ディレクトリ構造

ディレクトリの構造は、次の規則に厳密に従う必要があります。

  1. プロファイル: プロファイルフォルダには、プロファイルの定義ファイルが含まれています。プロファイル定義は、Azure Stack 一般提供バージョンと Azure Cloud で実行できるハイブリッド アプリケーションを対象としています。

  2. 仕様: このフォルダは、すべてのスペック(管理プレーンおよびデータプレーン)関連ドキュメントのルートフォルダです。

  3. {RP-Name} フォルダー - 各リソース プロバイダーには、少なくとも 1 つの個別のフォルダーが必要です。

    複数のフォルダが必要な場合は?これは、以下の考慮事項によって異なります。

    • RP フォルダーは、別の SDK パッケージにつながります。異なるサービス/コンポーネントエンティティに対して別々のSDKパッケージを持つことが期待されていますか?
    • 1 つのフォルダー内のサービス/コンポーネント エンティティは、同じバージョン管理サイクルを共有します。1 つのフォルダー内のサービス/コンポーネント エンティティが同じバージョン ラベルを共有し、将来一緒にアップグレードできますか。
    • 1 つの RP フォルダ内のスペシフィケーション ファイルとオートレスト構成ファイルは、同じ RP フォルダ内のファイルを参照することをお勧めします。注: RP フォルダ間で参照する必要があるエンティティ型定義は、フォルダ共通型の下に配置および管理する必要があります。
    • その他の考慮事項については、API 設計レビューのレビュー担当者に問い合わせてください。レビューを開始するには、Azure SDK の摂取に関するアンケートを送信してください。

    RP フォルダには、再調整マネージャまたはデータ プレーン Cadl 仕様を含めることができます。Cadl は、クラウド サービス API を記述し、他の API 記述言語、クライアントとサービス コード、ドキュメント、およびその他の資産を生成するための言語です。詳細については、CADL リポジトリ: Cadl チュートリアルのチュートリアルをご覧ください。また、社内の Teams チャネル Cadl ディスカッションでフィードバックを提供するための質問をすることもできます。

    リポジトリ内の Cadl ファイルの構造の詳細については、「Cadl リポジトリ構造」を参照してください。

  4. 'リソースマネージャ'と'データプレーン'フォルダ:RPは、(ARMリソースの場合)と(他のすべての場合)の2つのカテゴリのいずれかに仕様を置くことができます。RP のオートレスト構成ファイル () が存在する場合は、これらの両方のフォルダー内に存在します。

    resource-manager
    data-plane
    readme.md

  5. 'マイクロソフト。{ARMNamespace}' フォルダ: フォルダは 'リソース マネージャ' フォルダの下にのみ必要です。つまり、管理プレーン API 仕様でのみファイル パスに ARM 名前空間を含める必要があります。ARM名前空間とARMオンボーディングについては、RPオンボーディングのARMウィキを参照してください。

  6. プレビュー」および「安定」フォルダ: これは、サービス/コンポーネントのライフサイクルステージであるプレビューとGAにマップされます。たとえば、サービスがプレビュー ステージにある場合、プライベート プレビューまたはパブリック プレビューに関係なく、サービスの API 仕様をフォルダーに配置する必要があります。サービスが GAED 化されていても、コンポーネントがプレビュー段階にある場合、API バージョンにはプレビュー コンポーネント エンティティも含まれているため、フォルダーに配置する必要があります。フォルダーには、GAED サービスの API バージョンとすべての GAED コンポーネントが含まれている必要があります。

    preview
    preview
    stable

    Azure の重大な変更ポリシーは、フォルダー内の API 仕様とフォルダーにどのように適用されますか?実際、レポがパブリックかプライベートかがより関連しています。

    preview
    stable

    • プライベート プレビューのコンポーネントまたはリソースの種類を含む API 仕様、または限定パブリック プレビュー (AFEC の背後にある、または表示されるサブスクリプションの管理) は、プライベート リポジトリ、別名 azure-rest-api-specs-pr で PR レビューを開始することをお勧めします。また、これらのAPI仕様には破壊的な変更はありません。

    • 一方、パブリック リポジトリのメイン ブランチ (別名、azure-rest-api-specs) でパブリックになっているものはすべて、フォルダー内またはフォルダー内に関係なく、Azure のお客様との契約として扱う必要があり、Azure の重大な変更ポリシーに従う必要があります。

      preview
      stable

  7. API バージョン フォルダー: このフォルダーは、またはフォルダーの直接の子です。このフォルダーには、REST API 仕様とフォルダーが含まれています。

    preview
    stable
    examples

  8. 'example' フォルダ: example フォルダには x-ms-example ファイルが含まれます。API またはリソースのバージョンフォルダの下には、異なる API またはリソースタイプのバージョンに異なる例を含めることができます。

注: フォルダ名とファイル名に関する一般的なガイダンスについては、以下を参照してください。

specification

  • フォルダ名は単数形にする必要があります(つまり、「プロファイル」ではなく「プロファイル」) - これは英語以外の話者にとってあいまいさを取り除きます。
  • 汎用フォルダ名は小文字にする必要があります
  • 名前空間フォルダはPascalCased(すなわち、 "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 フォルダーの下にあるサービスまたはコンポーネント間でいくつかの共通のエンティティの種類を共有すること。

次のフォルダ構造サンプルでは、'resource-manager' フォルダのみがあります。「データプレーン」フォルダの下に同様のフォルダ構造があるかもしれませんが、サブコンポーネント/サブサービスフォルダは同じではないかもしれません。

フォルダー構造を初めて作成するとき、または現在のフォルダー構造を変更する場合は、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.md

AutoRest 構成ファイル (別名 readme.md) がサブサービス/サブコンポーネント フォルダーから配置されている場合、すべてのサブサービス/サブコンポーネントを保持する SDK パッケージは 1 つだけです。ファイルが各サブサービス/サブコンポーネントフォルダに配置されている場合は、各サブサービス/サブコンポーネントの個別のSDKパッケージがあります。SDK 生成用に AutoRest 構成ファイルを統合する際には、必ず Azure SDK ArchBoard for SDK パッケージ化戦略を参照してください。

共通型

1 つの RP フォルダ内のスペシフィケーション ファイルとオートレスト構成ファイルは、同じ RP フォルダ内のファイルを参照することをお勧めします。クロスリソースプロバイダーまたはサービスを共有できるエンティティ型定義は、仕様上の共通フォルダの下、またはサービスグループフォルダ構造の共通型フォルダの下に配置および維持する必要があります。前者は rp フォルダ間で共有するエンティティタイプをサポートし、後者は同じ rp フォルダの下でコンポーネントまたはサービスを共有する enitity タイプをサポートします。

.たとえば、「リソース管理の共通タイプ」を参照してください。

次のステップ

仕様が完成した後のプロセスの次のステップは、SDK と API リファレンス ドキュメントを生成することです。マイクロソフトの従業員である場合は、Azure SDK - 内部 Wiki で詳細を確認してください。

外部コントリビューターは「OpenAPI 仕様入門」を読むことができます。


このプロジェクトでは、マイクロソフトのオープンソース行動規範を採用しています。詳細については、行動規範に関するFAQを参照するか、opencode@microsoft.com にお問い合わせの上、追加の質問やコメントを添えてください。