Cursor での OSS ドキュメントの使用 - Object Storage Service - Alibaba Cloud ドキュメントセンター

Object Storage Service (OSS) ドキュメントを Cursor の AI ナレッジソースとして設定します。これにより、Cursor Agent は最新の公式ドキュメントに基づいて、標準の SDK 呼び出しコードと ossutil の使用例を自動的に生成できます。また、API 呼び出しの問題の修正や、正確な設定の推奨も可能です。

Cursor ドキュメントデータソースの設定

Cursor の @Docs データソースを設定することで、このドキュメントを Cursor に簡単に提供できます。

手順：

Cursor の設定を開く
- メニューバーで、[Cursor] > [Settings] の順にクリックします。
Docs 設定への移動
- 左側メニューで、 [Indexing & Docs] をクリックします。
- ドキュメント設定ページが開きます。
OSS ドキュメントソースの追加
- ドキュメントの追加をクリックします。[ドキュメント] パネルで、[ドキュメントの追加] をクリックします。
- 公式 OSS ドキュメントの URL を入力します：https://www.alibabacloud.com/help/oss/。「Aliyun OSS Docs」など、わかりやすい名前を入力します。
  
  表示された設定フォームに、次の情報を入力します：
  - [NAME]：Aliyun OSS Docs
  - [PREFIX]：https://www.alibabacloud.com/help/oss/
  - [ENTRYPOINT]：https://www.alibabacloud.com/help/oss/
  フォームの入力完了後、[確認] をクリックしてください。
- ドキュメントソースがリストに追加され、そのステータスが「インデックス済み」になっていることを確認します。ドキュメントソースが追加されると、ドキュメントリストにインデックスステータス (例: [インデックス済み 2556 ページ]) が表示されます。[アクション] 列の [インデックス済みページの表示] アイコン (ブックアイコン) をクリックします。表示されるパネルで、インデックス済みページのタイトルリストを表示して、ドキュメントが正常にクロールおよびインデックスされたことを確認できます。

Q&A のための OSS ドキュメントの使用

設定が完了したら、Cursor で OSS ドキュメントのデータソースにクエリを実行できます。

方法：

チャットウィンドウでの @Docs の使用
- Cursor AI チャットウィンドウを開きます。
- @Aliyun OSS Docs に続けて質問を入力します。
- 例：@Aliyun OSS Docs How do I use the OSS Java SDK to create a client and configure access credentials?

正確な回答の取得

AI は OSS ドキュメントに基づいて正確な回答を提供します。これらの回答には、コード例、設定手順などの詳細情報が含まれます。

Maven 依存関係の設定：

<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.17.4</version>
</dependency>

環境変数からの認証情報を使用して OSSClient を作成するための完全な Java コード例 (推奨)：

import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
import com.aliyun.oss.common.comm.SignVersion;

public class OSSClientExample {
    public static void main(String[] args) throws Exception {
        // 環境変数から認証情報を取得
        EnvironmentVariableCredentialsProvider credentialsProvider =
            CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

        // クライアントを設定
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        // V4 署名アルゴリズムを使用
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);

        // OSSClient インスタンスを作成
        OSS ossClient = OSSClientBuilder.create()
                .endpoint("your-endpoint") // 例：https://oss-cn-hangzhou.aliyuncs.com
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region("your-region") // 例：cn-hangzhou
                .build();

        // ossClient を使用して操作を実行...

        // 不要になったら OSSClient インスタンスをシャットダウン
        ossClient.shutdown();
    }
}

次の環境変数を設定してください： OSS_ACCESS_KEY_ID (AccessKey ID) と OSS_ACCESS_KEY_SECRET (AccessKey シークレット)。

クエリ結果の最適化

具体的に質問する：広範な質問は避けてください。特定の機能やシナリオについて質問してください。
キーワードを含める：質問に「bucket」、「object」、「permission」などの OSS 関連のキーワードを含めてください。

段階的に質問する：複雑な操作については、複数のステップで質問してください。

# 良いクエリの例
@Docs How do I use the Java SDK to upload a file to OSS?
@Docs How do I configure cross-origin resource sharing (CORS) for OSS?
@Docs How do I set permissions using a Resource Access Management (RAM) policy in OSS?
@Docs I need to upload a file to OSS in my Node.js project. Provide a complete code example.
@Docs Provide best practices for multipart uploads of large files to OSS.
@Docs Provide detailed troubleshooting steps for OSS CDN cache configuration issues.

# 避けるべきクエリ
@Docs How do I use OSS? (広範すぎる)
@Docs Upload file (コンテキスト不足)

OSS ドキュメントを使用したエラーの解決

Alibaba Cloud OSS SDK を使用してファイルのアップロード、ダウンロード、またはその他の操作を行う際にエラーが発生した場合、ドキュメントデータソースを使用してエラーを自動的に解決できます。

import alibabacloud_oss_v2 as oss

def main():
    # 環境変数から認証情報を読み込み、認証を行う
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # デフォルトの SDK 設定を読み込み、認証情報プロバイダーを設定
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # リージョンを設定
    cfg.region = "cn-hangzhou"

    # 設定済みの設定で OSS クライアントを作成
    client = oss.Client(cfg)

    # ローカルファイルからオブジェクトを直接アップロード
    # バケット名、オブジェクト名、ローカルファイルパスを指定
    with open('your-test-file.md', 'r') as f:
        result = client.put_object(
            oss.PutObjectRequest(
                bucket="xxx",  # バケット名
                key="xxx",        # オブジェクト名
                body=f.read()     # ファイル内容を読み込む
            )
        )

    # 結果を出力：ステータスコード、リクエスト ID、コンテンツ MD5、ETag、CRC64 チェックサム、バージョン ID、サーバーレスポンス時間
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
          f' server time: {result.headers.get("x-oss-server-time")},'
    )

if __name__ == "__main__":
    main()

File "/Users/xxx/xxx/py_proj/myenv/lib/python3.12/site-packages/alibabacloud_oss_v2/client.py", line 275, in put_ob...
    return operations.put_object(self._client, request, **kwargs)
File "/Users/xxx/xxx/py_proj/myenv/lib/python3.12/site-packages/alibabacloud_oss_v2/operations/object_basic.py", line 44, in put_object
    op_output = client.invoke_operation(op_input, **kwargs)
File "/Users/xxx/xxx/py_proj/myenv/lib/python3.12/site-packages/alibabacloud_oss_v2/_client.py", line 327, in invoke_operation
    raise exceptions.OperationError(
alibabacloud_oss_v2.exceptions.OperationError: operation error PutObject: crc is inconsistent, client 12522791075485846984, server 16472007160000755729.

Cursor Agent のチャットウィンドウを開きます。@Aliyun OSS Docs に続けて、特定の問題の説明を入力します。AI は最新の公式 OSS ドキュメントを使用して、正確なトラブルシューティング手順と解決策を提供し、コードの最適化とエラーの解決に役立ちます。

IDE に組み込まれている AI アシスタントダイアログに、 @Aliyun OSS Docs Please help me troubleshoot the error と入力します。チャットのコンテキストは、現在のコードファイル put_object_with_file.py とナレッジベース [Aliyun OSS Docs] を自動的に関連付けます。AI アシスタントは、ドキュメントとコードのコンテキストに基づいてエラーを分析し、修正案を提示します。

たとえば、ファイルアップロード中に CRC エラー alibabacloud_oss_v2.exceptions.OperationError: operation error PutObject: crc is inconsistent が発生した場合、AI アシスタントは自動的にエラータイプ (CRC64 データ整合性チェックの失敗、クライアントとサーバーの CRC64 値が不一致)、影響範囲 (PutObject、AppendObject、UploadPart) を分析し、根本原因がファイルをテキストモード 'r' で読み取っていることだと特定します。解決策は、 open('your-test-file.md', 'r') を open('your-test-file.md', 'rb') に変更して、ファイルをバイナリモードで読み取ることです。ワンクリックで修正できるボタンも提供されます。

AI アシスタントは、OSS SDK のファイルアップロードエラーに対して 2 つの解決策を提示します：
1. 推奨される解決策：ファイルをバイナリモード 'rb' で開く (✅ データ整合性を保証、✅ すべてのファイルタイプで動作、✅ ベストプラクティスに従う)
2. 一時的な解決策： put_object_with_file_disable_crc.py を作成して CRC64 検証を無効にする (⚠️ データ整合性の保護を失う、⚠️ 信頼できる環境でのみ使用、⚠️ 本番環境での使用は非推奨)
CRC64 検証メカニズム： SDK はデフォルトで CRC64 検証を有効にします。クライアントとサーバーはそれぞれチェックサムを計算して比較します。ファイルをテキストモードで開くと、行末変換が発生し、チェックサムの不整合を引き起こす可能性があります。ファイルを読み取るには、常にバイナリモードを使用してください。

OSS ドキュメントを使用した ossutil コマンドの生成

Cursor の AI 機能を使用して、自然言語で操作を記述できます。公式 OSS ドキュメントをデータソースとして使用し、Cursor はアップロード、ダウンロード、正規名 (CNAME) 設定などのタスクのためのコマンドライン操作を自動的に生成して実行します。AI はドキュメントと現在のファイルディレクトリを参照して、直接実行できるコマンドを生成します。

方法：

チャットウィンドウでの @Docs の使用
- Cursor AI チャットウィンドウを開き、@Aliyun OSS Docs に続けて操作の説明を入力します。
- 例：@Aliyun OSS Docs Use ossutil to upload the cname-configuration.xml file to the bucket named examplebucket

ドキュメントに基づいたコマンドの生成と実行
- AI は、現在のディレクトリに cname-configuration.xml ファイルが存在するかどうかを分析します。
```
Let me first check the files in the current directory:

Listed current directory

I can see the cname-configuration.xml file. Let me view the file content to understand its structure:

Read cname-configuration.xml
```
- 次に、説明の中の「upload」、ファイル名、バケット名などの主要な要素に基づいて、AI は公式 OSS ドキュメントから対応する ossutil コマンドを生成します。アクセス認証情報を設定している場合、Cursor はコマンドを実行することもできます。
  
  たとえば、次の ossutil コマンドを実行して、cname-configuration.xml ファイルを指定されたバケットにアップロードします：
```
ossutil cp cname-configuration.xml oss://examplebucket/

axxxxi@JGWL9Q2JP7 ossutil-2.1.1-mac-arm64 % ossutil cp cname-configuration.xml oss://examplebucket/
Success: Total 1 file, size 3882 B, Upload done:(1 objects, 3882 B), avg 14.731 KiB/s

0.260099(s) elapsed
axxxxi@JGWL9Q2JP7 ossutil-2.1.1-mac-arm64 %
```