API インテグレーションの作成

概要

Datadog API エンドポイントを使用して、バックエンドからデータをリッチ化して送信したり、Datadog から直接データを取り出したりすることができます。API インテグレーションは、Datadog と他の SaaS プラットフォーム間のコネクターを構築する際に効果的です。この方法は、SaaS ベースで、作成者が認可のためにログインするための既存の Web サイトを持っている技術パートナーに最適です。

API インテグレーションは、以下の種類のデータを Datadog に送信します。

このページでは、integrations-extras リポジトリで API インテグレーションを作成するための手順を説明します。API ベースのインテグレーションを作成する理由については、独自のソリューションを作成するを参照してください。API インテグレーションは、Datadog Agent を使用してデータを収集しないため、開発作業が完了したら、情報用のタイルのみのリストを作成する必要があります。

セットアップ

前提条件

API キーは、Datadog の API エンドポイントにデータを送信するために必要です。アプリケーションキーは、Datadog からデータをクエリしたり、Datadog サイト内でリソースを作成するために必要です。詳しくは、API とアプリケーションキーを参照してください。

API キー、アプリケーションキー、サイト URL を使用して、自社のプラットフォームで Datadog への接続を作成します。

OAuth クライアントを作成する

Datadog では、これらの資格情報をユーザーに直接リクエストする代わりに、OAuth クライアントを使用して、API ベースの統合のための認可とアクセスを処理することを推奨しています。詳細については、インテグレーションのための OAuth認可エンドポイントを参照してください。

Vantage のような integrations-extras リポジトリで、既存の API インテグレーションの例を調べることができます。

ディレクトリを設定し、integrations-extras リポジトリをフォークします。

  1. dd ディレクトリを作成します。

    mkdir $HOME/dd

    Datadog Development Toolkit は、$HOME/dd/ ディレクトリで作業していることを想定しています。これは必須ではありませんが、異なるディレクトリで作業する場合は、追加の構成手順が必要です。

  2. integrations-extras リポジトリを複製します。

    git clone git@github.com:DataDog/integrations-extras.git

Datadog Development Toolkit をインストールして構成する

Datadog Development Toolkit (ddev) を使用すると、インテグレーションに必要なディレクトリ構造、アセット、メタデータを生成することができます。

始める前に、以下の前提条件を満たしていることを確認してください。

  • Python v3.8 以降
  • 環境の競合を避けるために、Python の仮想環境を使用することをお勧めします。以下の説明では、ほとんどの OS で Python v3.3 以降に同梱されている venv を使用します。

Development Toolkit をインストールして構成します。

  1. integrations-extras ディレクトリの中にいることを確認します。

    cd $HOME/dd/integrations-extras

  2. Python の仮想環境を構築します。

       python3 -m venv venv
       . venv/bin/activate

    仮想環境は deactivate を実行することでいつでも終了させることができます。

  3. Developer Toolkit をインストールします。

    pip3 install "datadog-checks-dev[cli]"

    Z Shell を使用している場合は、pip3 install datadog-checks-dev\[cli\] を実行して、エスケープされた文字を使用する必要があるかもしれません。

  4. デフォルトの作業用リポジトリとして integrations-extras を設定します。

       ddev config set integrations-extras $HOME/dd/integrations-extras
       ddev config set repo integrations-extras

    integrations-extras ディレクトリの複製に $HOME/dd 以外のディレクトリを使用した場合は、以下のコマンドを使用して作業リポジトリを設定します。

       ddev config set integrations-extras <PATH/TO/INTEGRATIONS-EXTRAS>
       ddev config set repo integrations-extras

インテグレーションタイルスキャフォールディングにデータを入力する

dev コマンドを実行して、情報タイルのみの出品のためのスキャフォールディングを作成します。

  1. integrations-extras ディレクトリの中にいることを確認します。
    cd $HOME/dd/integrations-extras
  2. -t tile オプションを付けて ddev コマンドを実行します
    ddev create -t tile "<Offering Name>"

ddev コマンドで使用するオプションは、開発しているインテグレーションの種類によって異なります。ddev コマンドで作成されるファイルの一覧は、インテグレーションアセットを参照してください。

必要なインテグレーションアセットファイルを完成させる

インテグレーションに必要な以下のアセットが揃っていることを確認してください。

README

README.md ファイルを作成したら、以下のセクションを H2s (##) として追加し、インテグレーションのタイルに表示される内容を記入します。

ヘッダー名ヘッダー
概要API インテグレーションを購入しインストールすることで、ユーザーに提供する価値やメリット (例えば、すぐに使えるダッシュボード、ログ、アラートなど) を ## Overview ヘッダーの下に説明文を記述してください。

この情報は、インテグレーションタイルの Overview タブに表示されます。
セットアップH3 の見出し (###) に分けられた情報を含む、API インテグレーションを設定するためのすべてのステップを含みます。標準的なトピックは以下の通りです。

- アプリ内インテグレーションタイルを使用してインテグレーションをインストールする。
- Datadog の組織で適切なロールと権限でインテグレーションを構成する。
アンインストールAPI インテグレーションをアンインストールするためのすべてのステップを含めます。この情報は、インテグレーションタイルの Configure タブに表示されます。
収集データすぐに使えるメトリクス、イベント、またはサービスチェックに関する情報を含む、API インテグレーションによって収集されるデータの種類を指定します。

ログ、モニター、ダッシュボードなど、その他の収集データの種類を含めることができます。API インテグレーションがこれらのいずれかを提供しない場合、Data Collected セクションを追加する必要はありません。
サポートサポートチームへのメール、自社への電話番号、自社のドキュメントやブログ記事へのリンク、その他のヘルプ情報などを含む連絡先情報を箇条書きで掲載します。

メディアカルーセル

インテグレーションタイルには、画像とビデオのメディアカルーセルが含まれます。

テクノロジーパートナーは、インテグレーションタイルにビデオを追加することができます。プルリクエストでビデオをアップロードしないでください。代わりに、ビデオのコピーまたはダウンロードリンクを marketplace@datadoghq.com に送信してください。マーケットプレイスチームは vimeo_link を返信します。このリンクを manifest.json ファイルに追加すると、メディアカルーセルの中にビデオを含めることができます。

ビデオは以下の要件を満たしている必要があります。

ビデオ要件説明
タイプMP4 H.264
サイズビデオサイズは最大 1GB です。
ディメンションアスペクト比は正確に 16:9、解像度は 1920x1080 以上でなければなりません。
名前ビデオファイル名は、partnerName-appName.mp4 でなければなりません。
ビデオの長さビデオの長さは最大 60 秒です。
説明最大許容文字数は 300 文字です。

テクノロジーパートナーは、インテグレーションタイルのメディアカルーセルに最大 8 枚 (ビデオを含む場合は 7 枚) の画像を追加することができます。

イメージは以下の要件を満たしている必要があります。

イメージ要件説明
タイプ.jpg または .png
サイズ平均は 500KB 程度です。最大イメージサイズは 1MB です。
ディメンションアスペクト比は正確に 16:9 で、以下の仕様に適合している必要があります。

- 幅: 1440px
- 最低高さ: 810px
- 最大高さ: 2560px
名前英字、数字、アンダースコア、ハイフンを使用してください。スペースは使用しないでください。
カラーモードRGB
カラープロファイルsRGB
説明最大許容文字数は 300 文字です。

このテンプレートに従って、イメージ、ビデオサムネイル、ビデオを含むメディアカルーセルの media オブジェクトを定義してください。

manifest.json

"media": [
      {
        "media_type": "image",
        "caption": "A Datadog API Integration OOTB Dashboard",
        "image_url": "images/integration_name_image_name.png"
      },
      {
        "media_type": "video",
        "caption": "A Datadog API Integration Overview Video",
        "image_url": "images/integration_name_video_thumbnail.png",
        "vimeo_id": 123456789
      },
    ],

詳しくは、インテグレーションアセットリファレンスをご覧ください。

プルリクエストを開く

integrations-extras リポジトリで、画像 (ロゴやイメージなど) とアセットファイル (Changelog.mdREADME.mdmanifest.json など) を追加し、インテグレーションページで API インテグレーションのタイルのみの出品に追加するプルリクエストを開きます。自動テストは、プルリクエストが適切な状態にあり、更新に必要なすべてのコンテンツが含まれていることを確認するためにチェックを実行します。

レビュープロセス

プルリクエストが全てのチェックを通過すると、Datadog/agent-integrationsDatadog/marketplaceDatadog/documentation チームのレビュアーが、ベストプラクティスに関する提案やフィードバックを提供します。

フィードバックに対応し、レビューを再要求すると、これらのレビュアーがプルリクエストを承認します。

お役に立つドキュメント、リンクや記事:

お役に立つドキュメント、リンクや記事: