REST API

Oracle Cloud Infrastructure APIのリファレンスへのリンクと、リージョンのAPIエンドポイントのリストは、APIのリファレンスおよびエンドポイントを参照してください。

エンドポイントのベース・パスには、望ましいAPIバージョン(たとえば、20160918)が含まれます。アッシュバーン・リージョンに新しいVCNを作成するPOSTリクエストの例を次に示します:

POST https://iaas.us-ashburn-1.oraclecloud.com/20160918/vcns

Oracle Cloud Infrastructureでは、お客様がデプロイされているクラウド・サービスの既存のAPIに関して、コードの更新が必要となるような削除または変更を実施する日の12か月前に、あらかじめ通知いたします。

詳細は、Oracle PaaSおよびIaaS Public Cloud Servicesのピラー・ドキュメントのセクション4.3を参照してください。

すべてのOracle Cloud Infrastructure APIリクエストは、認証のために署名されている必要があります。必要な資格証明とリクエストの署名方法の詳細は、リクエストの署名を参照してください。

すべてのOracle Cloud Infrastructure APIリクエストは、HTTPSおよびSSLプロトコルTLS 1.2をサポートする必要があります。

Oracle Cloud Infrastructure APIでは、標準的なHTTPリクエストおよびレスポンスが使用されます。このトピックの別の箇所やAPIドキュメントで説明されているように、それぞれに、ページ区切りやエンティティ・タグ(ETag)などOracle固有のヘッダーを含めることができます。

各レスポンスには、一意のOracl割当てリクエストID (たとえば、bb3f3275-f356-462a-93c4-bf40fb82bb02)がopc-request-idレスポンス・ヘッダーに含まれます。特定のリクエストについてオラクル社に連絡する必要がある場合は、このリクエストIDを指定してください。

API操作の多くは、リクエスト本文にJSONが必要であり、レスポンス本文でJSONを返します。JSONの特定のコンテンツについては、個々の操作のAPIドキュメントを参照してください。JSONは、操作の名前またはオブジェクトの名前やタイプに基づいてラップまたはラベル付けされないことに注意してください。

POST https://iaas.us-phoenix-1.oraclecloud.com/20160918/vcns
host: iaas.us-phoenix-1.oraclecloud.com
opc-retry-token: 239787fs987
Content-Type: application/json
HTTP headers required for authentication
Other HTTP request headers per the HTTP spec

{
  "compartmentId": "ocid1.compartment.oc1..aaaaaaaauwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq",
  "displayName": "Apex Virtual Cloud Network",
  "cidrBlock": "172.16.0.0/16"
}

200 OK
opc-request-id: 6c4d01a6-f764-4325-a3f8-720c8b5cae7b

{
   "id": "ocid1.vcn.oc1.phx.aaaaaaaa4ex5pqjtkjhdb4h4gcnko7vx5uto5puj5noa5awznsqpwjt3pqyq",
   "compartmentId": "ocid1.compartment.oc1..aaaaaaaauwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq",
   "displayName": "Apex Virtual Cloud Network",
   "cidrBlock": "172.16.0.0/16"
   "defaultRouteTableId": "ocid1.routetable.oc1.phx.aaaaaaaaba3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdsq",
   "defaultSecurityListId": "ocid1.securitylist.oc1.phx.aaaaaaaac6h4ckr3ncbxmvwinfvzxjbr7owu5hfzbvtu33kfe7hgscs5fjaq"
   "defaultDhcpOptionsId": "ocid1.dhcpoptions.oc1.phx.aaaaaaaawglzn7s5sogyfznl25a4vxgu76c2hrgvzcd3psn6vcx33lzmu2xa"
   "state": "PROVISIONING",
   "timeCreated": "2016-07-22T17:43:01.389+0000"
}		

リクエストの結果がエラーの場合、レスポンスに標準HTTPレスポンス・コードが含まれます(クライアント・エラーは4xx、サーバー・エラーは5xx)。本文には、エラー・コードを含むJSONとエラーの説明も含まれます。例:

{
    "code": "InvalidParameter",
    "message": "Description may not be empty; description size must be between 1 and 400"
}

すべてのサービスに対する共通のエラーのリストは、APIエラーを参照してください。

Oracle Cloud Infrastructureは、リソースの偶発的または不正な使用を防ぐために、多数のAPIリクエストにスロットル調整を適用します。作成するリクエストが多すぎたり早すぎたりすると、成功するものと失敗するものがでてきます。数秒から最長で60秒までの指数関数的バックオフを実装することをお薦めします。スロットル調整が原因でリクエストが失敗すると、レスポンス・コード429と次のエラー・コードおよび説明が返されます:

{
      "code": "TooManyRequests",
      "message": "User-rate limit exceeded."
}

コンピュート・インスタンスなど、ほとんどのOracle Cloud Infrastructureリソースにはライフサイクルがあります。多くのケースで、コードがさらにアクションを行う前に、リソースまたは作業リクエスト が特定の状態になるまで、またはタイムアウトが超過するまで待機する必要があります。

リソースをポーリングしてその状態を確認できます。たとえば、GetInstanceをコールするとき、レスポンス本文にlifecycleState属性を含むインスタンス・リソースが含まれるとします。場合によっては、インスタンスのlifecycleStateがRUNNINGになるまでコードを待機させてから進める必要があります。

リソースによって、状態が変わる時間は異なります。したがって、ポーリング戦略にとって最適な頻度と期間のパラメータは、リソースごとに異なることがあります。Oracle Cloud Infrastructure SDKのウェイタでは、次のデフォルト戦略が使用されています:

• ポーリング試行の間に、数秒から最長で30秒までの指数関数的バックオフを実装することをお薦めします。
• 最長で20分までポーリングしてから停止します。

ウェイタの詳細は、次を参照してください:

• SDK for Javaウェイタのドキュメント
• SDK for Rubyウェイタのドキュメント

APIを使用する場合、リクエストに署名するためにテナンシ のOCIDが必要です(リクエストの署名を参照)。これは一部のIAM API操作でも必要になります。OCIDはOracle Cloud IDです(リソース識別子を参照)。

テナンシOCIDの例は、ocid1.tenancy.oc1..<unique_ID>です(「tenancy」という単語が含まれています)。

ほとんどのリスト操作では、結果のページ区切りが行われます。たとえば、コア・サービスAPIのListInstances操作では結果のページ区切りが行われます。ページ区切りのリスト操作をコールすると、レスポンスに、結果のその他のページを示すopc-next-pageヘッダーが含まれます。

ページ区切りコントロールはオブジェクト名のフィルタリングにも使用されるため、オブジェクト・ストレージListObjectsのリスト・ページは、動作が異なります。ListObjectsは、レスポンス本文でopc-next-pageのかわりにnextStartWithを返します。さらに多くのオブジェクトをページ区切りするには、返されたnextStartWith値をstartパラメータとともに使用します。ListObjectsから返されるオブジェクトをフィルタリングするには、startおよびendパラメータを使用します。

一部の操作では、一意の再試行トークン(opc-retry-token)を指定できるため、タイムアウトまたはサーバー・エラーの際に、同じアクションを再実行するリスクなしでリクエストを再試行できます。トークンの有効期限は24時間後ですが、操作が競合する場合はその前に無効化できます(たとえば、リソースがシステムから削除されてパージされた場合は、最初の作成リクエストの再試行が拒否される可能性があります)。

APIでは、オプティミスティックな同時実行性制御のためにETagをサポートしています。GETコールおよびPOSTコールは、格納する必要がある値を含むetagレスポンス・ヘッダーを返します。後でリソースを更新または削除する場合、そのリソースについて受け取ったETagをif-matchヘッダーに設定します。そのリソースが更新または削除されるのは、指定したETagがそのリソースのETagの現在の値と一致する場合のみです。

オプション・パラメータの値として空文字列("")を送信すると、APIはその値を通常どおりに検証します(たとえば、最小および最大許容値のチェックなど)。多くの場合、最小許容値は1であるため、エラーが返されます。値を設定しない場合(null)、APIは検証を実行せず、他のなんらかのアクションが発生する可能性があります。たとえば、新規VCNオブジェクトの作成時にdisplayNameの値を設定しないと、サービスによって自動的に値が生成されます。