REST API

Oracle Cloud Infrastructure APIは、HTTPSリクエストおよびレスポンスを使用する典型的なREST APIです。このトピックでは、APIの使用に関する基本情報について説明します。

APIバージョン

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


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

APIの破壊的変更に関するポリシー

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

詳細は、Oracle PaaS and IaaS Public Cloud Servicesのピラー・ドキュメントの6.3項を参照してください。

必要なリクエストの署名

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

必要なHTTPSおよびTLS 1.2

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

クライアント・クロック・スキューの最大許容値

クライアント・クロックのサーバーに対する誤差が5分を超える場合、HTTPステータス・コード401 (NotAuthenticated)が返されます。サーバーのクロック時間を確認するには、APIエンドポイントとともに次のcurlコマンドを使用します:

curl -s --head <endpoint> | grep Date

例:

curl -s --head https://iaas.us-phoenix-1.oraclecloud.com | grep Date

リクエストとレスポンスのフォーマット

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は、操作の名前またはオブジェクトの名前やタイプに基づいてラップまたはラベル付けされないことに注意してください。

ノート

本文にJSONを含むPOSTおよびPUTリクエストではContent-Typeヘッダーをapplication/jsonに設定してください。

CreateVcnリクエストの例


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"
}

CreateVcnレスポンスの例

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分までポーリングしてから停止します。

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

テナンシのOCIDを確認する場所

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

テナンシOCIDは、Oracle Cloud Infrastructure Console「テナンシ詳細」ページで確認できます:

  1. 「プロファイル」メニューを開き、「テナンシ: <your_tenancy_name>」をクリックします

  2. テナンシOCIDが「テナンシ情報」の下に表示されます。「表示」をクリックしてID全体を表示するか、「コピー」をクリックしてクリップボードにコピーします。

    テナンシOCIDの場所を示す「テナンシ詳細」ページ

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

リストのページ区切り

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

ノート

結果が残っていても1ページが空になる場合があります。opc-next-pageヘッダーがある場合は常に、さらに取得できるリスト項目が存在しています。リソース・リストの制御の詳細は、検索の概要を参照してください。

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

結果の次のページを取得するには

同じURLに対して、ページ問合せパラメータにopc-next-pageヘッダーの値を設定して変更した新しいGETリクエストを行います。opc-next-pageヘッダーを含まないレスポンスを取得するまで、このプロセスを繰り返します。このヘッダーが存在しないことが、リストの最後のページに達したことを示します。

ノート

ページ区切りコードを記述するかわりとしては、SDK for Pythonで提供されるページ区切りモジュールのファンクションを参照してください。
結果の前のページを取得するには
(一部のAPIに対応しています。)同じURLに対して、ページ問合せパラメータにopc-prev-pageヘッダーの値を設定して変更した新しいGETリクエストを行います。opc-prev-pageヘッダーを含まないレスポンスを取得するまで、このプロセスを繰り返します。このヘッダーが存在しないことが、リストの最初のページに達したことを示します。
ノート

ページ区切りコードを記述するかわりとしては、SDK for Pythonで提供されるページ区切りモジュールのファンクションを参照してください。
1ページ当たりの最大結果数を変更するには

GETリクエストで、limitにレスポンスで返される項目数を設定します。

ノート

サービスから返されるものがlimitに指定した数を超えることはありませんが、正確にその数が返されるとはかぎりません。

再試行トークン

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

オプティミスティックな同時実行性制御のためのETag

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

オプション・パラメータのnullおよび空文字列

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