Oracle Cloud Infrastructureドキュメント

REST API

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

警告

Oracle Cloud Infrastructure APIに機密情報を含む文字列値を使用することは避けることをお薦めします。

APIリファレンスとエンドポイント

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

APIバージョン

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


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

リクエスト署名必須

すべてのOracle Cloud Infrastructure APIリクエストは、認証のために署名する必要があります。 必要な資格証明およびリクエストへの署名方法については、「シグネチャのリクエスト」を参照してください。

HTTPSおよびTLS 1.2必須

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

許容される最大クライアント・クロック・スキュー

クライアントの時計がサーバーから5分以上ずれている場合、HTTPステータス・コード401 (NotAuthenticated)が返されます。 サーバーの時間を確認するには、このcurlコマンドをAPIエンドポイントとともに使用します:

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

例えば:

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

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

Oracle Cloud Infrastructure APIは、標準のHTTPリクエストとレスポンスを使用します。 各トピックには、このトピックの他の部分およびAPIのマニュアルで説明しているように、ページング用のOracle固有ヘッダー、エンティティ・タグ(ETag)などが含まれている場合があります。

各応答には、opc-request-idレスポンス・ヘッダーにOracle固有のリクエストID (たとえば、bb3f3275-f356-462a-93c4-bf40fb82bb02)が含まれています。 特定のリクエストについてOracleに連絡する必要がある場合は、このリクエスト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" }

エラー形式

リクエストの結果がエラーの場合、レスポンスには、クライアント・エラーの場合は4xx、サーバー・エラーの場合は5xxの標準HTTPレスポンス・コードが含まれます。 本文には、エラー・コードとエラーの説明を含む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です(「リソース識別子」を参照)。

「テナンシ詳細」ページでOracle Cloud Infrastructure ConsoleのテナンシOCIDを取得します。

  1. 「ガバナンスと管理」の下で「ナビゲーション・メニュー」を開き、「管理」に移動して、「テナンシ詳細」をクリックします。

    テナンシ詳細アイテムを示すナビゲーション・メニュー

  2. テナンシOCIDを「テナンシ情報」の下に示します。 「コピー」をクリックしてクリップボードにコピーします。

    テナンシOCIDのロケーションを示す「テナンシ詳細」ページ

テナンシOCIDは次のようになります(その中に"tenancy"という単語があります): ocid1.tenancy.oc1..<unique_ID>

リスト・ページング

ほとんどのリスト操作は結果を改ページします。 たとえば、コア・サービスAPIのListInstances操作では、結果のページ番号が付けられます。 ページングされたList操作を呼び出すと、レスポンスはopc-next-pageヘッダーを含めることによって結果の追加ページを示します。

ノート

結果がさらに残っていても、ページは空になることがあります。
opc-next-pageヘッダーが表示されるたびに、取得するリスト・アイテムが増えます。 リソース・リストの制御の詳細については、「検索の概要」を参照してください。

結果の次のページを取得するには
結果の前のページを取得するには
1ページあたりの最大結果数を変更するには

トークンの再試行

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

オプティミスティック並行性制御のためのETags

APIは、オプティミスティック並行性制御の目的でetagsをサポートしています。 GETとPOST呼び出しは、保存する必要のある値を持つetagレスポンス・ヘッダーを返します。 後でリソースを更新または削除する場合は、リソース用に受信したETagにif-matchヘッダーを設定します。 リソースは、提供するETagがそのリソースETagの現在の値と一致する場合、onlyを更新または削除します。

オプションのパラメータのNullと空の文字列

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