本ブログは、オラクル・クラウドの個人シリーズ・ブログの1つです。
初めに
Oracle Analytics Cloud (OAC)のスナップショットを作成するには、コンソールだけでなく、REST APIを使用することも可能です。日常のバックアップをスクリプト化したい場合、この方法が適しています。
この例では、プライベート・タイプのOACインスタンスをサービスGW経由でオブジェクト・ストレージにスナップショットを作成する方法を紹介します。
目次
1. 事前準備
この例では、REST APIを実行するクライアントは、OACインスタンスと同じサブネット内にあるComputeインスタンスです。ネットワークリソース（ルート表、NSG、サービスGW）の設定に関する詳細な説明は省略します。
1-1. 認証情報の取得
OACスナップショットはOCIオブジェクト・ストレージに保存されます。OACインスタンスがオブジェクト・ストレージにアクセスするためには、以下の認証情報を提供する必要があります。
テナンシOCID、ユーザーOCID、リージョンID、API秘密キー、APIキーのフィンガープリント
これらの情報は、OCI-CLIの構成ファイルの構成ファイルに含まれています。構成ファイルがすでにある場合は、そこから取得してください。まだお持ちでない方は、以下の方法で認証情報を取得してください。
アイデンティティ → 自分のプロファイル → APIキー → APIキーの追加
秘密キーをダウンロードし、追加ボタンを押す。
コピーを押し、構成ファイルの中身をメモしてください。
1-2. JSONファイルの作成
次のようにJSONファイルを作成します。
new_snapshot.json
{
"type": "CREATE",
"name": "myfirstsnapshot",
"storage": {
"type": "OCI_NATIVE",
"bucket": "OAC_Snapshot",
"auth": {
"type": "OSS_AUTH_OCI_USER_ID",
"ociRegion": "ap-tokyo-1",
"ociTenancyId": "<Tenancy_OCID>",
"ociUserId": "<User_OCID>",
"ociKeyFingerprint": "<your_fingerprint>",
"ociPrivateKeyWrapped": "<cat myprivate_key.pem | base64 -w 0>"
}
},
"bar": {
"uri": "file:///myfirstsnapshot.bar",
"password": "<to_give_your_snapshot_a_password>"
}
}
| 項目 | 値 | コメント |
|---|---|---|
| name | スナップショット名 | 例：myfirstsnapshot |
| bucket | 格納先のバケット名 | 例：OAC_Snapshot |
| ociRegion | リージョン識別子 | 例：ap-tokyo-1 |
| ociTenancyId | テナントOCID | STEP 1-1で取得 |
| ociUserId | ユーザーOCID | STEP 1-1で取得 |
| ociKeyFingerprint | 秘密キーのフィンガープリント | STEP 1-1で取得 |
| ociPrivateKeyWrapped | 暗号化された秘密キー | ※１ |
| uri | スナップショットのURI | ※２ |
| password | スナップショットのパスワード | 決めること |
※１、次のコマンドでAPI秘密キーをエンコードします。
Linuxの場合: cat myprivate-key.pem | base64 -w 0 > mywrapped-private-key.pem
Macの場合: cat myprivate-key.pem | base64 -o mywrapped-private-key.pem
※２、この例では、バケットの直下にオブジェクトを作成するため、フォルダは使用しません。フォルダを使用したい場合は、次のように記述してください。
file:///myfolder/myfirstsnapshot.bar
1-3. トークンの発行
スナップショットを作成するには、トークンを発行する必要があります。次の2つの方法のいずれかを使用できます。
方法-1. コンソールからダウンロード
アナリティクス・インスタンス → インスタンスの詳細 → 追加詳細
「アプリケーション」のリンクをクリックして、アプリの詳細画面に移動します。
「アクセス・トークン」を選択し、「トークンのダウンロード」を押してダウンロードします。（デフォルトのファイル名は、tokens.tokです。）
ファイルの中身：
{"access_token":"<トークン_中略>","token_type":"Bearer","expires_in":100}
※、有効時間は100秒です。
方法-2. CURLコマンドで取得
スナップショットの作成をスクリプトで自動化したい場合、この方法がおすすめです。トークンを発行するには、以下の情報を取得しておいてください。
ドメインURL
「追加詳細」のタブから取得できます。
例：https://<IDCS_instance>.identity.oraclecloud.com
スコープ文字列
上記画面で「アプリケーション」のリンクをクリックし、アプリの詳細画面に移動します。
「OAuth 構成」タブ
スコープ文字列の構成: 「プライマリ・オーディエンス」と 「スコープ」を結合する
例: https://<string>.analytics.ocp.oraclecloud.comurn:opc:resource:consumer::all
「クライアントID」と「クライアント・シークレット」
スコープ文字列と同じ画面から取得します。
取得後、次のコマンドでエンコードしてください。
echo -n client_id:client_secret | base64 -w 0
トークンを発行するコマンド
curl --request POST --url https://<IDCS_instance>.identity.oraclecloud.com/oauth2/v1/token \
--header 'authorization: Basic <echo -n client_id:client_secret | base64 -w 0>' \
--header 'content-type: application/x-www-form-urlencoded;charset=UTF-8' \
-d 'grant_type=password&username=<username>&password=<password>&scope=<scope>'
| 項目 | 値 | 例 |
|---|---|---|
| IDCS_instance | ドメインURL | https://<IDCS_instance>.identity.oraclecloud.com |
| 暗号化されたClient IDとClient Secret | echo -n client_id:client_secret | base64 -w 0 |
|
| username | OCI ユーザー名 | |
| password | OCI ユーザーのパスワード | |
| scope | スコープ文字列 | https://xxxxxxx.analytics.ocp.oraclecloud.comurn:opc:resource:consumer::all |
コマンドの出力結果：
{"access_token":"<トークン_中略>","token_type":"Bearer","expires_in":100}
2. スナップショットの作成
トークンはOACインスタンスが停止している場合でも発行できますが、スナップショットを作成するためには、インスタンスがアクティブな状態である必要があります。
curl -i --header "Authorization: Bearer ${access_token}" \
--request POST https://${hostname}/api/20210901/snapshots \
-d @new_snapshot.json
| 項目 | 値 | コメント |
|---|---|---|
| access_token | トークン | STEP 1-3で取得 |
| hostname | インスタンスのホスト名 | OACの「追加詳細」から取得できる。例：<host_string>.analytics.ocp.oraclecloud.com |
| new_snapshot.json | STEP 1-2で作成したファイル |
CURLコマンドの出力は、次のようです。
HTTP/1.1 202 Accepted
Date: <中略>
Content-Type: application/json; charset=utf-8
Content-Length: 35
Connection: keep-alive
X-ORACLE-DMS-ECID: 57a67cf4-ebbb-4ec7-8079-ae77795c2ddc-00002a86
ETag: W/"23-d9x1y9Mzt6zwWxjB98QRA9W8qp8"
oa-work-request-id: lfc-cj:7-ch:203
X-ORACLE-DMS-RID: 0
Strict-Transport-Security: max-age=31536000;
vary: X-Forwarded-Proto,origin
{"workRequestId":"lfc-cj:7-ch:203"}
最終行の「workRequestId」をメモしてください。
3. 進捗状況の確認
上記ステップの出力に作業リクエストIDが返されます。そのIDを使用して進捗状況を確認します。トークンの有効時間（100秒）が過ぎる場合、再発行してください。
curl -i --header "Authorization: Bearer ${access_token}" \
--request GET https://${hostname}/api/20210901/workRequests/${work_request_id}
- ${work_request_id} -- 実際の作業リクエストIDで置き換える。
※、進捗状況（status）は、３つ種類があります（"IN_PROGRESS","SUCCEEDED", "FAILED"）。
成功した場合、作業リクエストの詳細は次のように表示されます。
HTTP/1.1 200 OK
<中略>
{"id":"lfc-cj:7-ch:203","operationType":"CREATE_SNAPSHOT","percentComplete":100,"status":"SUCCEEDED","timeAccepted":"<中略>","timeStarted":"<中略>","timeFinished":"<中略>","resources":[{"resourceType":"SNAPSHOT","id":"<中略>","actionResult":"CREATED"}]}
OCIコンソールから作成されたスナップショットを確認します:
※、同じファイル名の既存のスナップショットがある場合、そのスナップショットは上書きされます。
トラブルシューティング
現象-1
スナップショットを作成した際に次のエラーが発生しました。
HTTP/1.1 401 Unauthorized
Date: <中略>
Content-Type: text/html
Content-Length: 172
Connection: keep-alive
www-authenticate: Bearer error="invalid_token", error_description="Token Expired"
vary: origin
考えられる理由：トークンの有効期限が切れた（100秒）。
対策：トークンを再取得し、有効期限内にもう一度作成してください。
現象-2
スナップショットを作成した際に次のエラーが発生しました。
作業リクエストの確認結果：
{"id":"<中略>","operationType":"CREATE_SNAPSHOT","percentComplete":100,"status":"FAILED","timeAccepted":"<中略>","timeStarted":"<中略>","timeFinished":"<中略>","errors":[{"code":"InternalServerError","message":"Cloud Storage Error"}]}
考えられる理由：オブジェクトストレージにアクセスするための認証情報が間違っている。
対策：new_snapshot.jsonの内容を確認してください。
以上です。
関連記事
オラクル・クラウドの個人シリーズ・ブログ
CLI/APIでOracle Analytics Cloudインスタンスを作成するために、アクセストークンを生成する方法
OAC ドキュメント
REST API for Oracle Analytics Cloud - Quick Start
REST API for Oracle Analytics Cloud - Create a snapshot
OCI CLI コマンド・リファレンス
Docs » analytics